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SECTION 7 


By Rich Morin 

More Basic Commands 


and a first look at “shell scripts’' 

Previous “Se<.tion 7' a)lumns liave looked at several BSD 
coiTimtinds, but tliey haven’t stiitl much abcjut die ways in which 
commands get perfoniied. Let’s do tliat now, stinting with die Tenniiial 
application. Eitch lime you stiirt tip a new Temiinid window, Mac OS 
X has to start up a program to t:ilk to it. Tlie program it starts is a 
“comiiiiind interpreter”, most often referred to as a “sliell”. 

Whenever a Tenninal w^indow Ls active, your keylxjard Is tied to 
tlie ^'standard input" of die program dial is currendy ninning '‘in" the 
window. Similarly, the window'.s text area displays die prcsgram ts 
''sLindaid output’', ff the shell starts up another progiam (such as Is), 
die .shell must “kran'" the.se I/O connections to die other program. In 
short, a Terminal window is always connected to some pnigiam; most 
often, tliis will lie the shell. 

Each shell runs as a .sepanite piDc:ess, so the "state" that gets .set 
in one "shell .ses-sion” is not shared with other shell .sessions. Thus, if 
you use cd to change the "current directory” in one 'reminal window, 
the shell sessions in your other windows will not Ix" adeemed. 

Because cd affects infrirmation that the shell must fiiaintain (and 
hand off to any programs El starts up), cd is actually "built in" la the 
shell itself. Most commands, however, are not built into the shell. 
Instead, diey are implemented as: 

• aliases or shell functions - lliese are sec|uenc\^s o\ commancLs, kept 
in die shell's memory and inieipretcd U[X)n demand. 

• shell scripts - lliese are sequence.s ol' commands, kept in .separate 
files and intcrpretcxl upon demand. Sometiiiies die shell iiself will 
interpret the script; other times, as discussed Ixiow, it w ill start up 
a separate [>rtjgram to do so. 

• executable iiinaiies - Tlie.se [ire sepamte programs, kept in 
.separate files and excxtiled upon deimtnd. To run them, the shell 
must fbrk(2), then exLxC3) die relevant file. 

In die case oi buili-ins, alkisc^, and .shell functions, die sliell 
'‘knows" wiitit needs to lx done. Jn the case of .shell .scripLs and 
executable binaries, iKnvever, it must find die requested file, determine 
its nature, and prtxecd accordingly. 

If a cc^mmtuid is not a built-in, an alias, C3r a .shell function, the 
shell looks for an executable hie of th^it name in one of .sevemi 
directories. Because die shell may cache t!ie contents of these 
directories in an internal data structure, .some shells rexjuire die u.ser to 
run a spexial ct^minand ("reliaslT) when a new^ command is added. 
Hie list of these directories, called the '’.search padi", Ls contained in the 
$padi vtiriable: 


[localhost :^] rdin% echo $path 

/Users/irdm/bin/powerpc'apple-darwin /Users/rdm/bin ... 

Tiic which cxjmmand can be used to predict the shells’ Ixliavior 
tor a given coiiinxind: 

[localhost:^ rdm% which cwd 1 
ewd: aliased to echo $cwd 

1: aliased to la -Ig, 

[localhost rdnf/.. which cd echo setenv 
cd: ahell built-in comraaiid, 
echo: ahell built’in coramarid. 
aetenv: shell built-in command. 

[localhost :■“] i:dm% which apropos keytool 
/uar/bin/apropos 
/uB r/bin/keytool 

Finding and exec uting files (e.g., /usr/bin/apropos) takes time, but 
it allcjws us to add new commands quite tiivialiy. imagine how 
aw'kwanl and cotistraining it would lx- if each new comniiHid had to 
be linked into the shell! 

Now that w'e have the ffiJI path names of die commands, we can 
examine them a bit: 

[localhoBtrdm% cd /usr/bin 
[localhost;/usr/bln] rdinX file apropos keytool 
apropos: Mach-0 executable ppc 
keytooJ: Bourne shell script text 

As IIIe inibrins us, /ti.sr/fiin/apropos Ls an executable binary file for 
the Pc3WerPC, ena)ded in "Mach-O” format. /usr/bin/kcTTcxd, in 
contrast, is a text file which must lx nm inLerpreiivcIy by sh (the 
''lk)umc shcl]”) as a "shell .script". Ikit wait a .second; liow' do file (and 
tlic shell) know that? Maybe it’s lime to take a ltx)k [it /usr/bin/keviool: 

I localhost:/us r/bin I cdiTi% cat keytool 
! /bin/sh 

|f Shell wrapper to launch keytool. 

The first two cliaracters of the tile ("^[” ) tel! the u.ser’s sheU diat fills 
is a script. Hie rest ol the line gives the full path nanie (‘'/l:>in/slT) of 
the program which mii.st be used to inleqirel file script. Because each 
saipl lan declare its fjwn language (eg,, Bourne .shell, C shell, Perl), 
new scripting language.s can lx added at any time. 

If a .script Stans with a sharp sign (“ff"), hut not the “ff!” sequence, 
it is treated as a C shell sciipL If a script begins with any other 
character, it is treated as a Bourne shell script. Finally, you may 
encounter .scripts that .start like "ff|/u.sr/bin/env perl". This tells file 
system to run /usr/bin/env, wliich will then go off and lincl file 
“appiopriate" copy of perl. 


Rich Morin has been using computers since 1970, Unix siiicr 19B3, und MaL-Lju;rt:d Unix since 1986 (wlicn he IxIijclI Apjjlc: create A/'VX 1.0), ’'Jt'Ficn 
lie isn’t w riting this column, Rich run.s Prime Time Preew^aie (www.ptf.com), a publisher of bcxks and CD-ROMs for the Free and Open Source softw^are 
community. Feci free to wrrite to Rich at txim@ptf.com. 
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The s'Atnt holder information is used by file to detemiine the type 
of a given file. To see file's list of ‘'magic numbers" (and 
interprelatiorLs)^ let's look at /etc/imgic: 

[localhost^/usr/birx] cdjBa cd /etc 
[localhost:/etc] rdml wc -1 magic 

3B27 /etc/magic 

[localhostt/etc] rdjn% grep ’shell script* magic 
0 string //l/bin/sh Bourne shell script te3tt 

“wc -1'' (word count, in line mode) tells us tliat there are about 4K 
lines in /etc/magic, so we don't try to list it. Instead, we use grep 
(global regular expression print) to display lines that contain the .string 
“shell scTipt". 

As discussed last month, most of BSD’s “system metadata’’ (e.g., 
c’ontn^l files, log files) Ls kept in ASCII fonmat. ITiLs works well with 
BSD’s wide range of text pixxiessing Lcx>ls, alkjwing us to extraa and 
process informatic^n in a very flexilile manner. 

If /etc/m;igic had been enctxled in some proprietary, binary 
format (e.g., MicTosoft Word), the exercise alxwe would have required 
us to start up a particular application. And, if ilie application wasn’t 
able to do wliat we wanted, wed have been stymied. 

Scripting ianguages 

BSD provides a variety of scripting languages. You are free to use 
any, all, or none of them, as you prefer. Hem are some (biased :-) 
notes that may help you in making your selections: 

• Tlie Bourne shell (sh) is not particularly a>nvenient as an interactive 
command interpreter, but it works well as a programming language. 
IBe Kom and Z shells (ksh, zsh) are upward]y<ximpatible versions 
of tlie Bourne shell. Tlie former Ls not supplied as pm of Mac OS 
X, but dte latter is and may deserve a kx)k. 

• llie Boume-Again sheD (bash) is upwardly compatil>le with the 
Bourne shell, but it also lx>rrows a variety of features from other 
shells. It is the default shell for most linux distributions, but it Ls 
not supplied as part of Mac OS X. 

• Tlte C shell (csh) is very^ convenient as an inieractive command 
interpreter, but it loses badly as a programming language due to its 
lack of syntax recognition. For example, multi-line commands 
always require backslashes at the end of m>n-temiinal lines, even 
when die sheD should be able to recognise that die command isn't 
finished. Most BSD systems, including Mac OS X, aaually pitjvide 
tcsh, ratiier than csh. As the tcsh man page says: 

“tcsh is an enlianced, but completely compatible, version of csh(T). 
It is a command language interpreter, usable bodi as an interactive 
login shed and as a shell-script a)mmand processor It includes a 
comiTitind-line editor, programmable word aimpletion, spelling 
coirection, a liLstory' mechanism, job control and a C-like syntax.” 

• Awk (aw*k) is a convenient and simple scripting language, suitable 
for simple formatting and calculation tasks. 

• If things start to get too complex for Awk or the shell to handle, 
you should probably turn to Perl (perl). Ped is an exUemely 
powerful language, with a laige and active user community. 

• Pyilion and Ruby are objea-oriented scripting languages widi small 
but vocal followings. Neither language is supplied as part of Mac 
OS X, but (like the odier languages mentioned above), they are 
readily available for you to download and install. 

• Finally, if you're a Tcl fan, you might want to try out tclsh C'a sheO- 
like apf^liGition dial reads Tcl commands”). 
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VIEWPOINT 


By Rich Morin 

Privacy by Default 


Making Rendezvous safe 
“for the rest of us"" 


Allhough Apple does noi use these words to describe it, 
their new Rendezvous system is designed to enuble 
"opportunistic, promiscuous’^ IP disawery. That is, it will take 
advantage of any opportunity to collect IP information (hence, 
oppoiiunistic) and it will happily interact with any cooperative 
system (hence, promiscuous). These cjtaractLTistics make 
Rendezvous extremely convenient for the user. 

Unfortunately, the same characteristics could also make 
Rendezvous extremely convenient for anyone who wainis to 
“listen in’" on network traffic. If a user walks into a 
conference facility or coffee bar with a Power Book, liow' 
many uninvited recipients will see his network traffic? 

rd like to see Apple provide "convenienl privacy", as 
part of its convenient networking, To he specific, I’d like 
them to implement “opportunistic, promiscuous'’ packet- 
level encryption, basedon IPSec and related standards. This 
isn't a new idea, by any means. 'I'he "Linux FreeS/WAN” 
project (http://www,freeswan,org) lias been w^crking on it for 
several years now; their early releases are currently being 
tried out in the field. 

The highdevel view of FreeS/WAN is quite simple. If my 
system has a packet to send to your system, it will first 
attempt to set up a VPN (Virtual Private Network), using 
IPSec, etc. If your system doesn i lionor the request, my 
system will simply send the packet "in the clear". 

If your sysrem does understand the request, how'ever, 
both systems wall send off for each otliers' public keys (e.g., 
from each others' DNS servers). The iw'o systems will then 
perform a key exchange, with the result that they both end 
up with the needed "sessRjn keys". Et voila, we have a VPNl 
The low-level description is a bit more c(?mplicated, but 
some folks may find it interesting. See 
http://www.freeswafi.org/freeswanJrees/freeswan-l.95/dot:/intro.[itml if you’re 
into that son of thing,,. 


Meanwhile, let’s look at some of the implications of the 
technology. In general, privacy and security tend to be at 
odds with convenience. And, as we all know, w^hen "1 really 
slioLild" gels in a fight with “I don’t want to", it usually loses. 
Consequently, although PGP and other strong privacy tools 
have been around for several years, they aren’t actually used 
very much. Even SSll has had an uphill fight against its 
(demonstraiily insecure) predecessors. 

By making netwajrk privacy the default, however, Apple 
could remove the "convenience factor'" from Lite equation, Joe 
and Sally Sikspak don’t have to install privacy software, set 
Uji keywords, or any of that hassle. Better yet, they don’t 
have to decide which programs (or files, or ,..) deserve 
encryption. No decisions, so no misiakes! In fact, they don’t 
even have to know that encryption is going on; their packets 
are simply a hit safer from .snooping, 

Apple likes to be seen as a standard-setter. By allying 
themselves witli the Linux FreeS/WAN project (and, ideally, 
providing an Open Source BSD implementation), Apple C()uid 
help to make opportunistic privacy an established standard. 
'Fhere are no guarantees, of course, but privacy and 
auiheniication are very .salable attributes these days... 

Even without total buy-in by the computer industiyc the 
effects of opjx>nunistjc encryption could be quite dramatic. 
For instance, it would be quite possible io set up a 
FreeS/WAN “gateway sender’’ at an ISP or on the border of a 
LAN. providing encryption capability for any external traffic. 
Like the Sikspaks, the machines being protected would never 
need to know that their packets were being encrypted. 

In addition, large-scale use of packet-level encryption 
would make it much harder to single out encrypted data 
streams for attack. If even 5% of the Internet's traffic is 
cnciy^pted, the mere fact of encryption is no longer an 
“interesting” cliaracteristic for snoopers. 


Rich Morin has been using computers since 1970, Unix since 1983, and Mac-based Lfnix since 1986 (when he helped Apple create A/LIX TO). When 
he isn’t writing this column, Rich runs Prime Time Freeware (www.ptLcom). a publisher of hooks and CD-ROMs for the Free and Open Source software 
community. Feel free to write to Rich at rdm@ptf.com. 
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CETTIMG 

STARTED 


By Erick J. Tejkowski 


REALbasic Plug-in Development 


Pluming Made Easy 


Introduction 

Back in ktc 1999. we first discussed REALbasic plug-ins in 
MacTech. Since then, mucli has cfianged. REAL Software has 
released several improvements to the REALbasic plug-in SDK, 
countless developers have created plug-inSj and lots more plug¬ 
in cDde is out there fcjr you tc> expltJre, llecause so much has 
changed, we revisit the topic of REALbasic: plug-in development 
this month* As we did nearly three years ago, we will examine 
the process of creating phig-ins for REALbasic. We will start with 
a brief description of the plug-in SDK features. Then, we will 
prepare the compiler for REALbasic plug-ins. Finally, we will 
code some plug-in examples so you can see how It all w^orks. In 
the process, we will discuss what has changed in the SDK during 
the past three years. If you are completely new to RHALhasic 
plug-in programming, this article should give you a good start on 
learning the skill. 

Plug-in Fundamentals 

Wdien we last looked at tlie RiilALbasic plug-in SDK in 19^)9, 
plug-ins could l>e compatible eitlier 6HK or PP(" Macintosh 
applicatiorLS, Since then, REAL Software added Microsoft Windows 
and Macintosh Carbon targets to ilie list of REALbasic’s abilities. 
Starling with REALbasic 4, they also removed supptJrt for the h8K 
target. This rncan.s lliat the eurrenl REALbasic plug-in SDK 
supporLs the creation of Pl^C, Carlx)n. and Win32 plug-ins* Each 
plug-in can cemtain any combination of these targets, but it must 
always l>e conipatifjle w^ith the platform where you are using 
ILEAlbasic. For example, if you plan to use tile plug-in w\ih a 
Classic version of REALbasic, your plug-in must have a PPC- 
compatible versifin for it to work. Likew ise, the Carbt^n version of 
ItEALbasic reejuires a C^arixm-cxanpaiible version of the plug-in. 

A REALbasic plug-in consists of one or mc3re code 
resources. The following list shows each possible target platform 
and iLs corresponding resource name: 

• Carbon - TICN’ 

• PowerPC (FPC) - “PLPC^ 

• Wm32-TL86’ 

Plug-in resources start at resource ID #128 and increment 
from there on. However, you will seldom or never have more 


than erne resource for each target* Thus, most plug-ins that you 
build will have one res(5urce (#128) for each target (i.e. TLPC\ 
PLCN\ and 

The current REALbasic plug-in SDK gives you the ability to 
cieate the following items: 

• Classes 

• Class Extensions 

• Controls 

• Functions 

• Database Engines 

In this article, we wall look at how' to implement each of 
these, except database engines. 

Before you emliark uptjti any REALbasic plug-in 
development, you should first visit REAL Software's web site and 
pick up a copy of the laLe.st plug-in SDK. The SDK URL appears 
at the end of this article in the Bibliography section* 

Prepare: the Q)MPiij*K 

To begin creating REALbasic plug-ins, you will need a 
ccanptler. The tool of choice here is Metrowerk's CodeWarrior. 
.Since REALbasic plug-ins must contain PEE code resources, 
Apple's Project Builder is not suitable for the task. Project Builder 
can only create Mach-O code. 

The easiest w^ay to build a plug-in is to use one of the 
exainpie projects included with the REALbasic plug-in SDK as a 
base. If you prefer to start from scratch instead, create a folder in 
the Finder named “MacTech Pktg-hU. Next, open your copy of 
the REALbasic plug-in SDK and copy the folders named “Glue 
Code" and ‘includes" into the “MacTech Plug-in" folder. Then, 
launch CodeWarrior. 

Create a new project in CodeWarrior using the Mac OS C 
Stationery. In the resulting New Project dialog that appears, 
select the Mac OS Toolbox: MacOS Toolbox PPC project 
stationery as shown in Figure 1. 


Erick Tejkowski is the author of REALbasic for Dummies. Y{>u can reach him at etejkow.ski@jmac.com. 
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New Project 

: Select preject stationery; 

! , Project Stationery 

j T MacOS Toolbox 

MecOS Toolbox Carbon 
MacOS Toolbox PPC 

b- Stan<fari Console 


* ^ar>eei"^ ^ OK ^ 


Figure 1. Choose Mac OS Toolbox PPC Project Stationery to 
begin biiilding a piug4n 

Since a RHALbasic pkig-in is a code resource, you need to 
make some changes to die settings of your Code Warrior project 
From the Targets tab, control-click die target named '"Classic 
Tooltxijx Debug'' and select clear from die resulting jxipup menu. 
If you based your project on tlie Classic T'oolliox stationery^ the 
remaining target will be named "‘Classic Toolliox Finaf'. 

Select Classic Ibolbox Final Settings from the Edit menu. 


This displays the settings panels for the current target. In the 
Target Settings Panel, change the Target Name to “PPC Plug-in”. 
Next, choo.se the Access Paths Panel and add a path to the 
“Includes” folder you copied earlier. Then, select the PPC 
Target Panel and adjust it to look like Figure 2. Note that the 
Creator field has changed since w^e last examined plug-ins in 
1999. h is now^ ‘RI5v2'. 



Figure 2. PPC Target Settings Panel 

Einally, .select the PPC Linker Panel and change it to match 
Figure 3 When you are finished, close tlie Settings window to 
return to tlie Project window. 


The fastest road to Apple Help starts here. 
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If you would like to create targets for Carbon or Win32, 
consult the REALhasic Flug-in SDK in the ^Targeting New 
Platforms’' section, llie process works much the same way, l.iLit 
you will need to make a few tweaks specMic to each platform, 
Again, your best bet for starting out is to tise one of the plug¬ 
in examples available in the SDK. lliose examples have already 
made tlie necessary project settings for each platlbnii. Sijuply copy 
the folder that contiiins one of tliese projects, and renanie it to your 
liking. Once opened, you may want to alter tlie ‘'Filename" setting 
in the PPC or X86 Taiget Panels h>r each target. You may also need 
to change the Access Paths Panel to match your directory strLicture. 
Otlier than that, a pre-made plug-in is ready to g{) and can greatly 
simplify' your life. Use them whenever possible! 

Gu)BAl Mtrt'Hoos 

By this point, you should have a plug-in project shell that 
needs some code. As i7ientioned earlier, we will look at 
ijuplementing global functions, classes, class extensions, and 
controls, llie plug-in will foctcs on QuickTime. QuickTime has a 
large set of functions that are compatible for PPC, Carbon, and 
Win32. Tbis simplifies matters, because you can often use (he same 
code for multiple taigets; even decidedly “Mac-looking" ccxle 
w'orks with Win32. It is alst} handy for RFALbasic users, becau.se 
REALbasic does not have some of these QuickTime features, 

Tlie simplest construct you can create in a REALliasic plug¬ 
in is a glol>al method. Simply create a ftinction as you normally 
would. For exam[>le, listing 1 shows how to toggle the 
MighQuality setting of a RHALmovie. 

listing 1: Toggle the lligliQuality Setting of a REALraovie 

Set MciviePUytl inUiFvinf 

static void SetHoviePlayHlntsFunc( REALmovie theMovie. Boolean 
theState] 

I 

QT::Movie aHovie; 

//get the QT movie from the REAJ,movie struct 
aMovie - REALgetMovieMovie{ theMovie ): 

//if we have a movie, set it's highQuality on/off 
if (aMovie) 

\ 

if (theState) 

S etMoVie P1ayHint s 


(aMovie. hintsHighQuality, hintsHighQuality) r 

else 

SetMoviePlayHlnts(aMovie, 0. hintsHighQiiallty); 

I 


1 


Note the REALtnovie parameter in the SetMoviePlayHintsFunc 
function. A REALtxisic user will want to pass a l^iEALIiasic movie to 
hiis lunction. We must tlien convert it to a Quickl unc movie for use 
witli stmdard QuickTime API calls. REALgetMovieMovie does tliis 
job lor us. REALgeLMovieMovie is a function provided by the 
REALliasic Plug-in SDK. The documentation for the Plug“in SDK lists 
all of the functions that are available to plug-in developers, dlie bulk 
of the SDK functions Iielp you to convert back ^ind forth iTetween 
REAliyasic and C/C++ tkita types and structures. 

To let your plug-in know' about tills function, you must define 
it using ccxle like that shown in listing 2. 

listing 2: Define a Global F unct ion_ 

SetMovicPhyHintsMetlrad 

REALmethodDeflnition SatMoviePlayHititsMethod = 

I (REALproc] SetMoviePlayHintsFunc. REALnoImplatnontatlon, 
'■'SetMoviePlayHlnts(theMovie as Movie, state as Boolean]" 1; 


SetMoviePlayl lintsMethod Is the name of the RFALmetliod 
w'itliin the plug-in code. Vtlien you call from REALbasic, tjie 
Sc^LMoviePlayHiiiisFunc function in turn is called. The last part of the 
KtvALnietliodDefinition shows how the call appears to REAliasic 
users. Choose your pliony parameter names carefully here, because 
LhL 7 are what appear in tlie Tips window of REALbasic. Figure 4 
shows what tlie Tips Window' looks like w'hen invoked for the 
SetMoviePlayl lints melliod. 

qI /tv SetMovtePlavNmts theMovie, state 


Figure 4. The 7ips Window displays a fundiorPs parameter 
names, hut no data types. 

The final step in adding a global function to a REALlDasic plug¬ 
in is to register it. Every REALbiisic plug-in has a PluginEntry 
functitin, It is here that you register the plug-in's methods, classes, 
extensions, and controls. Listing 3 shows how to register the 
SetMoviePlayHintsMethod via a PluginEntry function. 

Listing 3: The PluginEntry Function 

I'he [dugiiiEiiiry funcrion is the entry point of n plugdn. Mere you register tlie various 
items (classes, controls, metlitKls. etc,.) that you want incjudetl in the ptug^in, 

void PiiigirLEntry(void) 

I 

REALRegisterMethod t&SetMoviePlayHintsMethod): 

J 


Class Extensions 

Global methods are usehil and easy to implement, but soon 
you w ill discover tfutt tliey do not fill all of your REALbasic plug 
in needs, Suppose^ for example, that you wished to add some 
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properties or mellitxis to m existing REALbasic ckss. Tlie 
RFALbasic Plug-in SDK gives you Che means to accomplish a cask 
like this via a Class Extension. 

To illustrate Class Extensioas, we will add a new property 
to the MoviePlayer control to permit users to play every Frame 
of a QuickTime movie. The properties are defined in Listing 4. 

listing 4; Define a Class Extension Propertyi 

MovicPIayerProperties 

REALproperty HoviePlayerPropertles(| ^ t 
I nil* "PlayEveryFrame", ’^Boolean"* 0, (REALproc) 

GetPlayE veryFrame, (REALproc) SetPlayEveryFrame 1. 

D 

This defines a new Botjlean property of the MoviePlayer 
called PlayEveryFrame. The *'getter" function for the property is 
GetPlayEveryFrame, while its “,setter'' is SetPlayEveryFrame. 
Listing 5 shows the definition of the setter and getter functions 
for this new property 

Listing 5: MoviePlayer Class Extension Properties 

(a'tPiaj'Fvco’Fninit: and SctPkyEvmFramt 

Set inil get tlie value of Oass Extension's Prrjperty with these two hinLiions. 

static Boolean GetPlayEveryFraine(REALmoviePlayer instance* long 

param) 

f 

Boolean everyFrame = false; 

KovleController thePlayer: 

thePlayer = REALgetHoviePlayetCont roller {.instance): 

MCDoActlon 

(thePlayer, mcAotionGetPlayEveryFraiie* ^everyFrama); 
return (everyFrame): 

I 

static void SetPlayEveryFrameCREALmoviePlayer instance* long 
param. Boolean state) 

r 

tiovleCantroller thePlayer: 

thePlayer ^ REALgetMoviePlayerController(instance); 

If (state) 

MCDoAction 

(thePlayer * mcActionSetPIayEveryF tame * (QT:;Ptr)true)■ 

else 

MGDoActlon 

(thePlayer* mcAGtionSetPlayEveryFrame. (QT: :Ftr)falae); 

] 

Setter and gener functioas for pro[’)enies look like mexst C 
functioas, but they liave a few' unique aspects tliat clisiuiguLsli them 
f\\m\ say, a gldial iiiethcxJ. First off, getter and setter functions Ibr 
properties have two requisite panimeters. In this exam[3le, tliey are: 

REALmoviePlayer instance, long pa ram 

The first parameter is the class to which the control [belongs. 
The second parameter (a long) is an extra variable for passing 
information around the plug-in. We do not use it in this 
example, but it is required in the function's definition and 
prototype. Tlte setter function has an additional parameter, 
which corresponds itj the data type of tlie REALbasic properly 
lieing added via the Claas Extension* 


With the properties declared and the setter/getter 
functit)ns in place, the next step is to place them into a Class 
Extension Definition, Lifting 6 illustrates the MoviePlayer Class 
Extension definition. 

Listing 6: Defining a Class Extension 

MovicPlaycrExicnsion 

REALclassDsfinitlon MoviePlayerExtension = I 
kCurrentREALCont rolVe rsion, 

’'MoviePlayer” * 
ail* 

0 * 

0 . 

nil* 

nil* 

MoV1e P1ayerP rope rt1es * 

fii^eafiKoviePlayerproperries] / elzeof(REALproperty). 

): 


A Class Extension uses a reference to a REALclassDefinition 
structure. The helcls of this structure are shown in Listing 7. Each 
field is optional, but you need to include all fields up to and 
including tlie last one you want to use. In our Clasps Extension, 
we chose to stop alter defining the MoviePlayerProperties, since 
we do not need any I iekl beyond iliat. 


Listing 7: REALclassDefimdon Fields 

L vmion the verMon of the pliipin ^irchitcetiirc that the eontrol was built under; 

fusi pass the eonsoni kCiirreniRL\IX’untmlVcrsion 
Z. mmc: the name of the class as used In RFAUsasie 
3. superNamc: the a:mic of the class’s superclass; 

mu.st be a built in class or a plug in class registered prior to this one 
■L daiaSizc: the si/x' cjf the cuSU^m data structure aIkKiated for each t^hject. 

NOTE: this data structure must Ik- the same size on all platforms 
(use [^adding if necessary)! 

5. fodiystemlfse: reserved (set to zefo) 

6. constnicior function to call to initialL;tc yemr custom data 
destructor: function to call to destrety your custom data 

B, properties: a reference to the array of propert)' declarations for the class 

9. propertyCiHint: the number of properties for the class 

10 meiliiKis: a reference to the array of method dechLnitions for the class 

11. meihodCount: the numher of method dcLiarations for the class 

12. events: a rcfea-nce to the array of event declarations hir the ebss 

13. cventCoimt: die numl>er of event declarations for the class 
N.eventinsiances: a reference to an array of event liandJers tor the class 
1 '5,evcntInstanceOmnt: the number of event handlers there arc 

16. iniLTfaces: a comma-delimited string of names of the interfaces 
supported by diLs conirol 

t7, bindi>escriptitm.s: a reference to an array of binding de,scriptii)ns for tills control 
IH. biadDcscriptionOmnt: the number of binding desciiptions there are 

Finally, register the Class Extension as you did with the 
global method earlier. 

PluginEntiy v2 

void PluginEntry(void) 

I 

REALRegisterMethod(&SetMovleFlayHintflMethod): 
REALRcginterClaasExtension(^MoviePlayerExtenslon); 


Controls 

Class Extensions are limiied creatures. Since Class 
Extensions extend existing structures, you are nor permitted to 
add custom data to them . Classes and Controls, on the other 
hand, are defined by you, so you can add as much custom data 
to them as desired. Since Classes and Controls are so closely 
related* w'e will limit our discussion to Controls. Any pointers 
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you pick up about Controls will usually carry over to Classes. 

To demoastrate how to create a REALbasic Control, we will 
build a simple viewer for displaying the various images one might 
fine in a multiple image file. QuickTime supports a few image file 
fijimats that allow multiple images in one file. Some of the more 
popular ones include Photoshop (.psd) and multi-page TIFF ( tif). 

The first step is to create a data structure that will store the 
image being displayed by die control. 


MuJatnugtrDatu 

struct HultilmageData 
{ 

REALpict u r e theImage; 

h 

To make sure that the Control redraws correctly, we need 
to define a Behavior for the Control The REALbasic Plug-in SDK 
lists all of the possible behaviors you might include, but we will 
only concern ourselves with one: redrawFunction, the tliird field 
in a Behavior structure. Simply name die function you will use 
to redraw the Control in the third field when defining the 
Controls Behaviors. 

MuJtilmagcBchuviour 

REAL control Behaviour Multi TmageBehaviour = t 
nil. // iniL ihr contiol 

nil, //dispiist- 

MultiIraageDrav // mlniw tlw tunmil 

]; 

Keep in mind that the MultilmageDraw' function is 

respoasible for draw'ing the Control w'hile the RKAl.hasic 
applic'aiion runs as well as when it is displayed in a w^indow' in 
the IDE. In the IDE, we wall fill in the Control with a blue color. 
During nintime, we will draw an image (if we have one loaded). 


Muia[nugcnr:i\^' 

static void MultiIiiiageDrav[REALcontrolInstance instance) 
t 

QT::Rect myRectr 
short myWidth*myHeight; 

RGBColor fillCol - [0.0.01: 

// gel a rcfercnee m the control'j^ diita strutiun' 

ControlData 

[MliI ti Image Con t rol. instance, Hui tl Image Data. data): 

// how big is the control? 

REALGetCantrolBounida(Instance, AmyRect): 

// if wc art- in the IDE, simply draw 
// a blue Ixix 

If tlREALinRuntimeO) 

I 

//fill in the control with blue 
fillCol.red - 0: 
fillCol.green = 0: 
flUCol.blue “ 65535: 

RGBFtjreColart&flllCol): 

PaintRect(&myRect}: 

I 

else 

[ 

//dmw an ima^t if we arc in the Rnntimc 
myWidth “ myRect.right myRect.left: 
myHeight ^ myRect.hottom ■ myRect.top: 

if (data->theImage) 

E 

REALDratfPicturePriinltivetdata->theIraage. ^myRect* D): 

I 


1 

1 

The Control will have two methods to tell us how many 
images are in a file and to draw a specific image in the Control. 
Define them as shown in Listing 8: 

Usting Si MnUlfnageControl Methods 

MuJtdniageMetliods, Loadlmagc, and ImageCountfunc 
REALmethodDefinlticrn MultllmageMethods[] = [ 

! (REALproc) Loadlmage, REALnoImplementation. 
"LoadlmageFileEFolderltem as Falderltem. pgNuni as integei:) 1, 

( (REALproc) ImageCountfunc, REALnoImplementation. 

"ImageCount(Folderltem as Folderltetn) as integer" 1, 
h 

static void Loadlmage 

{REALcontrolInstsnce instance, 

REALfolderltem myRF, long pgHum) 

I 

//get !i reference to the ctmirejl'ts data sinicture 
ControlData 

(MilltilmageConttoll instance. MultilmageData. data] | 
int imgCount: 

imgCaunt “ ImageCountfimc(instance. joyRE): 
if ( imgCount > 0) 

I 

//gci an image l>ased on l-bLised index 

data >thelinage ^ GatImageBylndexfujic(myRF. pgNum): 

//refresh ibc commit tamge 
MultiliDageDraw (instance): 

1 

ElBe 

1 

data->theTraage =■ nil: 

1 

1 


static int IumgeCountfutic(REALcontro 1 Instance instance. 

REALfolderItern myRF) 

( 

//retujmi image couni of a file 

Componentlnstance glmporter: 

unsigned long myCount: 

OSErr cnyErr - QT::noErr; 

FSSpec pjyFSpec: 

iny Count = 0: 

ControlData 

(MnltilmageContml, instance. MultiltBngeData. data); 

if (lREALFSSpecFroraFolderttem(&rayFSpec, myRF)) 
rettirn; 

myErr = CetGraphicalraporterForFiletBmyFSpec. 6glmporter): 

if (myErr t“QT::nnErr) return (myErr): 

myErr = GraphlcalmportGetlmageCount 

(gimporter. &myCouni): 

if (myErr 1= QT::noErr} return (32): 

if (glniporter != MUI.L] 

CloscComponent(gimporter); 

return myCount: 

1 

You mighl have noticed ilvdi these Control functions have a 
parameter much like the Properties of die Class Extension 
presented earlier. This is required and gives you access to the 
instance of the contrcj). This in turn permits you to access the 
Control's data structure. 
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MavieController thePlayer: 


Next, define the control Again, consult the SDK to see all 
the possible fields in the REALcontrol structure. 


MullilitugcControl 

REALcontrol MultllmageCoTitroi = I 
kCurrentREALControlVersion. 

“Hu 1111 ma geVl ewe t “ , // name of Contnil 

slzeofCHultilmageData). 

0. // for Invisible controls, use; EEALinvlsibleControl 

123. // PICT resource for tocilbar 

129. // PICT resourice for toolbar (tlcppi'iisca) 

320, 240 , // the tlelauli sb;c of the control 

nil. // no properties this lime... 

0. // sizeoffprapertks) 

Hult iLmageMethod s. // the methixls 

fiizeoftMultilmageMethods) / sizeof(REALmethodDefinition). 
nil. // the events 

0. it sizcoftevents) 

&MultiImageBebaviou r 

)r 

Finally, register the Control in the PluginEntry. 

REALRegisterControi{&MultiImsgeControl3 : 

The complete plug-in code is shown in Listjng 9- 


Listing 9: MacTechPluginxpp 

// MacTechPlugin.cpp 

// Demonsinites a simple REAll>ask- plug-in 

ft 

//Targets: Classic, Carbon 

II 

if REALhasic vcrsRjn used in denm; 4,(12 
// 

// CodeWarrior version used in demfx 6 - 

//Version 7 should alsj> work without any ptt^cct ch.uiscs 


#in c1ud e "Mac Tec hP1u gin.h“ 


jr***GLOBAL METHOD 


Static void SetMaviePlayHintsFunc 

[ REALinovle theMovie, Boolean theState ) 

1 

QT:;Movie aKovie; 

//get die QT movie from die REALmovie struct 
aMovie " REALgetMovicMovleC theMovie 3 : 

//ir we have a movie, set it's liigliQualiiy on/off 
if (aMovieJ 
( 

if (theStateJ 

SetMovleP1ayEinta 

EaMovle, bintsfiighQuality, hintsflighQuallty); 

else 

SfitMovlePlayHlnts(aMovie. 0. hintsHighQuality): 

) 

I 

// c:uss EXTENSION - MoviePlayer 


REALproperty HoviePlayerPropertles[] - ( 

f nil. "PlayEveryErame". “Boolean”, 0, (REALproc) 
GetPlayEveryFranie, [REALproc] SetPlayEveryFrante 1. 

); 

Static Boolean GetPlayEveryFrame(REALmoviePlayer instance, 
long patam) 

[ 

Boolean everyFrame = false; 


thePlayer “ REALgetHovlePlayerGontroller(instance); 
HGDoActlon 

(thcPlayer, meActionGetPlay EveryFrame. ieveryFrame) ; 
return (everyFrajae); 


static void SetPlayEveryFrameEREALmovieFlayer instance, long 
param. Boolean state) 

1 

MovieController thePlayer: 

thePlayer = REAL|etMoviePlayerController(instance]; 
if (state) 

MGBoAction 

(thePlayer, mcActionSetPlayEveryFrame. (QT;;Ptr)true); 

else 

MCDoAction 

(thePlayer, mcActionSetPlayEveryFrarae, (QT;:Ptr)false): 


// CONTROL ■ Muitilmagc viewer 
// ■ for image foes that might 

// hold more dun one image 
// iff, etc,.,) 

extern struct REALcontrol MultlloiageControl; 


Etruci MultilmageData 

1 

KEALpicture thelmage: 

Ir 


static void HultilroageDrawCREALcontrolInstance Instance) 

i 

QT;;Rect rnyRect; 

short rayWidth.myHelght: 

RGBColor flllCol - [0,0.01; 

// gel a reference to the etmtrors data structure 
ControlData 

(MuItiltnageControl. instancEH MultilmageDats. data]; 

// htJw big is the control? 

REALGetControl Bounds (instance. SiinyRect) i 

// if wc am in die IDE, Jiimply draw 
// a blue box 

If (!REALinRuntime(]) 

I 

//fill in the control with blue 
flllCoi.red ” 0; 
fillCol.green = 0; 
flllCol.blue = 65535; 

RGBForeCQlor (&finCoi]; 

PalntRect(6myRect3: 

) 

else 

[ 

//draw an image, if we arc in the Runtime 
myWidth = myRect,tight ■ myRect.left; 
myHeight ” myRect.bottom - myRect.top: 

if Cdata->thelmage) 

( 

REALDrawPictursPrimitive(data->theImage. ^myRcct, 0); 

) 
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1 

I 

static void LoadImage(REALcontrolInstance instance. 
REALfolderltem myRF. long pgNura] 
f 

//get 1 retlrenee to die coaLDol's data stmcmre 
ControlData 

(MultilmageCoiitrcil. instance^ MultilmageQaTa, data): 
Int imgCount: 

itngCount = ImageCountifunc (instance < myRF): 

if ( ImgCount > 0) 

t 

//get an iniagp based on 1-based index 

data Othe Image = GetImageByIndexfune (inyRP. pgNmii): 

//refresh the control's iamge 
MultiIitiageDrav( instancej; 


I 

else 

I 

data■ >theljiiage nil; 


//retujus image count of a file 

static int ImageCountfuiic(REALcontrolInstance instance, 
REALfolderltem myRF) 


Componeiitlnstance 
unsigned long 
OSErr 
FSSpec 

rayCount “ 0; 

ControlData 

(MultilniageGontral. instance. MultiImageOatan data): 

if (EREALFSSpecFr offlFolder Item (&niyFS pec ♦ myRF)) 
returns 

myErr = GetGraphicsIniporterForFlIe (&tayFSpec , ^glmpottet): 
if CmyErr E= QTssnoErr) return CmyErr): 
my Err “ Graphics ImportGetlntageCount 

(glinporter. limyCount): 
if {myErr E= QTsinoErr) return (32); 

if (gltnporter E’^ NULL) 

CloseComponent(gimporter) s 
return myCount: 


ginjporter: 
myCount; 

myErr ^ QT::noErr; 
myFSpec; 


t 


//load an image into the controi using 1-based index 

static REALpicture GetImageByIndexfunc(REALfolderltem myRF, 
int indx) 

f 


Comp onentInata nc e 

qt; sRect 

unsigned long 

OSErr 

OSErr 

FSSpec 


glmporter; 
myRect: 

myCount. myindex: 
myErr - QT:snoEcr: 
err = QT::noErr; 
myFSpec; 


if (lREALFSSpecFtomFQlderIte[n(S:myFSpec, myRF)) 
return; 


myErr “ GetGraphicBlmporterForFile (imyFSpec , iglmporter); 
if (myErr != QT;snoErr) return (REALpicture)NULL: 
myErr - GraphicsIraportGetlmageCount 

C gImpo rt er. SmyC ount )I 

if (myErr 1^ QT:;iioErr} return (REALpicture)NULL: 

//loop through all of tlic layers 
//and look for the one we want 
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//(i.c,inds) 

for (mylndex = h ntyrndex <= tnyCount: nrylndex++) 

{ 

if (tnylndex ^ indx) 

{ 

myErr ” GraphicsIffiportSetlmageltidex 

fgiraporter. mylndex): 

If CrayErrl^QT:rnoErr) goto baili 

GrapbicsIiiiportGetNaturalBounds{gImporter* imyRect); 

//Do ihc CiWorid stuJf 
GlrfqrldPtr world; 
ntyErr = NewGWorld 

£ World, 8, &inyRect> NULL, NULL, 0}; 
if (err 1“ QT: inoErr) returii (R£ALpictiire)NIlLL; 

//set port and draw 
GrapLicsIjnportSetGWorld 

(gitoporter* (CGrafPtt)world, NULL): 
GraphicslniportDr3¥(gTiiiporter): 

if [glmporter NULL) 

CloseComponent(giroporter): 

return (EHALBuildPicfureF rntiiGWo rid (world, true)): 

) 

1 

bail: 

if (glaiporter 1= NULL) 

CloseComponent(glmporter): 
return £REALpic:ture}NlILL; 

1 


REALclasEDefinitioti MoviePlayerExtenaloii “ I 
kCurrentREALGontrolVeraion, 

"MoviePlayer", 
nil, 

0, 

0 , 

nil, 

nil, 

MovlePlayetPropertles, 

sizeof(MovlePlayerProperties) / sizeof(REALproperty), 
nil, 

Q, 

nil, 

a. 


REALmethodDeflnition HultilmageMethqdBI] ” I 
[ (REALproc) Loadltnage, REALnoIiipleJiientatlon, 
"LoadImageFile(Foldarltem as Folderltem, pgNum ae integer!" 
), 

1 (REALproc) ImageCountfunc* REALnoIitrplementation, 
"ImageCount(Foiderltem as Folderltem) as integer" 1, 

h 


REALcontrolBehaviour MultilmageBehaviour = [ 
nil. // init the coninil 

nil. //dispose 

Multi Ima ge D r a w // it dmw ihe eonirol 

1 ; 


REALoantrol MultiImageControl ” [ 
kCurrentREALControlVersion, 

"Mult ilmsge Vi ewer " , // name of coniml 

slzeof (MultilinageData} , 

0, 

128, // PtCT resource ftir toolbar 

129, // PJerr resource for Uh ill)ar (depressed) 

520,240. // the default size of the control niJ, 

// no properties this time... 

0, // sizeoffpropcTties) 

Mu 11 i I mageMe tho d s, // the methods 

sizeof(MultilmageKethods) / sizeof(REALmethodDefinitinn), 
nil, //the events 


0, //size<if(evcnts) 

&Mu 1 tl Inia geEeha vi our 

1 ; 

REALmethodDefinltiun. SetHovlePlayHintaMethod = 

I (REALproc) SetMoviePlayHintsFunc, REALnoImplementation. 
"SetMoviePlayUints(theHovie as Movie, slate as Boolean)" i: 


^pragma mark - 

void PluginEntry(void) 

I 

REALRegisterKathod(^SetMoviePlayHintaHethod}: 
REALRegisterClassExtensionf&HovieFlayerExtension)i 
REALRegiaterControl(fitMultilmageControl); 

1 

Conclusion 

This time we lookecJ at how to build a REALbasic plug-in 
consisting of a global niethcxl, a Cla,ss Extension, and a Control. 
Although we only scratched the surface of plug-in possibilities, this 
at least gives you a good start for l>eginning plug-in development. 
Check the various resources li,sted in the bibliography if you need 
more help and above all, happy pluggingl 

BlBUOGRAPffY 

Tlic Internet provides the bulk of information about 
REALhasic plug-in development. Start at REAL Software's site 
and download the laie.st SDK. Then, sign up for the REALhasic 
plugdn list. Many talented plugdn programmers frequent the lists 
and often pn wide valuable assistance. 

REALsoftware 

http://wwvv.fealsoftvvare.conn 

The mother ship.,, visit here often. 

REALbask Plug-tii SDK 

http://webster,realsoftware.com/download/release.hlml 

Required visiting! The SDK provides all the files you need to get 

started programming REALhasic plug-ins, 

REALhasic Plug-iJis List 

http://webster.realsoftwafe.com/support/internet.html 

Need help? Join the REALbask Plug-ins list and a.sk away! 

Thomas Tcmpelmanji 

http://www.tempet.org/rb/index.html 

Here you'll find many great REALha.sic plug-in code examples. 

REAlJbasic Plugin Programming 

Erick Tejkow.ski 

http://www.mactech.com/artides/m3ctechA/ol, 15/15.10/REALbasicPlugin/ 
index.html 

The original MacTech REALhasic plug-in article from 1999^ 
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Awesome!” 


“The power, quality and feature set of 
Lesso Professional 5 is very impressive. 
The new documentation is definitely 
among the best in the business." 

Johan Solve; Ha/mstad, Sweden 


'"Blue World has managed to add an 
immense amount of functionality and 
scalability without sacnficing any of the 
ease-of-use of previous versions. New 
features lilte LassoApps, custom tags 
and UssoScript create a development 
environment that seems almost limitless," 

Tom Wiebe; Vancouver, Canada 
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Lasso 

Professionals 


Quickly BuidPcfwirfuf 


"With Lasso, I have been able to single- 
handed I y develop sophisticated solutions 
for internal and external use in less time 
than I see teams of people take with 
other middleware languages." 

Greg W^flrts; Santa Ana, Calfforn^a 


"This new release, I have got to adnnit, 
is truly amazing. The rich array of new 
features, the brand new documentation 
and the amazing new administration 
interface make Lasso Professional 5 
definitely worthy of a purchase." 

Bnarr Oken; Srookfyn, New York 


Upgrade today to the most powerful Web application server for 
Macintosh and beyond and you'll discover why so many Web 
developers claim Lasso Professional 5 is the must-have tool for 
quickly building and serving powerful data-driven Web sites. 

Lasso Professional 5 introduces a next-generation, object-oriented 
Web programming language, advanced Web application server 
administration, an embedded Lasso MySQL'''^ high-performance 
database server, a new distributed architecture, new platform and 
data source support, unprecedented extensibility and customiza¬ 
tion, 1800 pages of rewritten documentation and over 200 new 
features and enhancements. Lasso Professional 5 provides vast new 
power and features while maintaining the fegendary ease-of-use, 
performance, and reliability that make Lasso the preferred tool for 
tens of thousands of Web developers, ISPs, and IT/IS professionals. 



T -.. 

Lasso Admintstration controls your entire setup via an 
attractive and intuitive Web browser interface. 



If you're serious about building and serving data-driven Web sites, 
but don't want to spend a serious amount of time getting it all to 
work, there's no better choice than Lasso Professional 5 . 

Visit the Blue World Web site today and see how Lasso products can 
help you quickly build and serve powerful data-driven Web sites. 

Lasso - The Leading Web Tools for Macintosh and Beyond 



Lasso Database Browser provides instant access to all 
your databaseSj without writing a line of code. 


blueworld 

www.blueworld.com 


O 2001 Blue WDrJd Commuriitabor^s. Irtc. MySQL Is a trad0rTiark of MySQL AB. PileMaker Pro Is a registered trademark of FileMaker, Inc. Lasso, Lasso ProfesEranai, LaSSOApp, LassoScript 
and Blue World are iradem,arks of Blue World Corrirnunications, Iw. All rights reseirved 

























APPLESCRIPT 
AMD COCOA 


By Bill Cheeseman, Quechee, VT 

AppleScript Studio: Implementing a 
Document-Based Application 


Saving and Retrieving Documents the 
Cocoa Way in AppleScript Studio 


In the previous anicie in this series, we helped Sir Arthur 
Conan Doyie to start writing an AppleScript document-based 
application called “Doyle"’ using AppleScript Studio. We began 
by designing the graphical user interface in Inieri'ace Builder, 
including a Preferences window and a Doyle Usage Log 
window. We also scripted Doyle's preferences system so that a 
user could save a preference to show or hide comments in the 
Usage Log. We left until this, the third aiticle in the series, the 
scripting of tJie Usage Log itself, including saving it to disk and 
reading it back. 

Before turning to the Usage Log, however, we must fix the 
bug that we found in Doyle's preferences system at the end of 
the previous installment. 

UPDAllNG THE USER IlVl'ERfAt J* FDR PRErERENCES—REVISITED 

In the previous article, we created the 
PreferencesController/applescript file to act as a ModebView- 
Controller {MVO “Controller” script coordinating the preferences 
.system’s “Model” (its data, managed by the 
PreferencesModel.applescript script) with its “View" (the 
graphical user interface, namely, the Preferences window' and its 
one checkbox). In the preferences Controller script, we 
implemented the Choose Menu Item event handler, connecting 
it to menu item Application -> Preferences in MainMenu.nib. 
Recall that the Choose Menu Item event handler did only one 
thing: it loaded the Preferences.nib nib file that archives 
information about the Preferences window, A separate Will 
Open event handler then set the appearance of the checkbox in 
the Preferences window to match the actual preference value 
and made the window visil)ie. 

The fact that the Clioose Menu Item event handler loads the 
nib file when the user chooses tlie Preferences menu command 


is both a plus and a minus. On the plus side, it enJiances 
application perfonnance by loading the Preferences window 
object “lazilyf that is, only if and when the user requests it. This 
speeds application launching by delaying until later the loading 
of the Preferences nib file, and it also makes the application’s 
initial memory footprint smaller. On the minus side, our first 
version of the Choose Menu Item event handler may load 
multiple copies of the nil) file, and it may therefore leave 
multiple Preferences windows open on die screen. This happens 
Ixicause the nib file is loaded indiscriminately every time the user 
chooses the Prelerences command, even il” the nib file was 
already loaded previously, Furthemiore, closing the Preferences 
window does not unload ihe nib file but only makes the window^ 
invisible, so our application could fill memory with multiple 
instances tif the window^ even if they aren’t visible, (An Interface 
Ikiilder setting could have been used to release the window 
objects memory aulomalically w lien the window is closed, but 
ihis would come at the expense of having to reload it when the 
window is opened again J 

To fix our hug, we w'ill add some statements to check 
w hether the nib file is already loaded when the user chooses the 
Preferences command. We will do this by in.serting another If 
clause in the Choose Menu Item event handler, The traditional 
waiy 10 do this sort of thing in a Cocoa application is to test 
whether the Objective-C “instance variable” representing the 
object is null. We will do something very similar here, deciaiing 
a new property', prefsWindow, and setting its initial value to null. 
We will load the nib file only if the property is still null. We will 
change iJie value of the property from a null reference to a 
reference to the new w'indow the first time the window is 
opened. In addition, if the property is not null, w'e must bring the 
window to ilie front and make it visible in case it w^as either 
closed {le., not visible) or it was already open but hidden behind 
the Doyle Usage Log window. 

Finsi, declare the new prefsWindow property. The 
PreferencesController.applescripi script already has a Properties 
.section, so add this declaration immediately following the 


Bill Cheeseman i.s a retired lawyer now making his living as a Macintosh developer and loving every minuie ck ir He is uniquely qualiried to wdre 
about AppleScript Studio, having served as webma.sTer of Tlie AppleScript Sourcebtx)k (www AppieScriptSourcebook.com) for many years and having 
also written a Cocoa tutorial, Vermont Recipes - A Cocoa Cookbtxik (www.stepwise,com/Articles/VermontRecipes/). 
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declaration the prefsModelLib property we created in the 
previous article: property prefsWindow : null 

Second, we set the value of the new property so that it 
refers to the new window object once the Preferences window 
has been opened for the first time. We already implemented the 
Will Open event handler in the previous article. Because this 
event handler brings with it a reference to the Preferences 
window object, add a new^ statement to tlie existing Will Open 
event handler, at the lieginning of the if title clause, as follows: 
set prefsWindow to theWindow 

Third, rewrite the existing Choose Menu Item event handler 
so that it is identical to the new version shown in listing 1. It 
inserts a new If/Else clause in the if tide, clause, testing wiiether 
the prefsWindow property is null, d' it is, it loads die nib file as 
before. If not, it brings the Preferences window^ ( which exists, 
but may or may not be visible) to the front and makes it key. 
Normally, in the classic Mac OS, a window is brought to the 
front within its application layer by setting its index to 1. We 
could therefore try set index of prefsWindow to 1 (and set 
visible of prefsWindow to true, if necessary'). However, this 
doesn't work correedy in AppleScript Studio 1.0. Instead, 
therefore, as a temporary workaround, we use AppleScript 
Studio's Call Method handler, which enables us to call Object!ve- 
C Cocoa methods from AppleScript. In this case, we call the 
Cocoa make Key And OrderFront: acdon method defined in the 
NSWindow class, which makes the window the key window and 
brings it to the front — just what we needed. 

Listing 1 

on choose menu item theMenuItem 

- Opens the Prefca^necs window. 

- Connected to menu item Application -> Preferences in MamMenn.nib, 

~ and potentially to odier menu items. 

if title of theMe nil Item is ""Preferences^.” then 
if prefEWindow is not null then 
- nib Preferences'' is already^ loaded 
call method ""makeKeyAndOrdecFront: ” 

of object prefsWindow with parameter null 

else 

load nib "'Preferences" 
end if 
end if 

end choose menu item 


This solution works, but it may fail in a later release of 
AppleScript Studio. Recall from the previous article that, in the 
initial release of AppleScript Studio, AppleScript properties are 
not persistent. Here, this means that the prefsWindow property 
we just added to PreferencesConrroller.applescript will revert to 
null every time the application is launched, and our scheme will 
w^ork as intended, However, if persistence is restored to 
AppleScript properties in a later release, our prefsWindow' 
property will retain a reference to the Preferences window 
object every time Doyle is relaunched, and that reference will 
undoubtedly be invalid. 

To fix this potential problem in anticipation of a future 
release of AppleScript Smdio, we will explicitly reset the value 
of this property to null when the user quits Doyle. Save your 
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work in Project Builder Then open MainMenu.nib, our main 
application nib file, in Interface Builder select the File's Owner 
icon in the Instances tab of the MainMenu.nib window^ and 
select the AppleScript pane in the File's Owner Info panef 
Under the Application group, check the ‘'should quit" event 
handler. The Application .applescript script is already checked, 
so click Edit Script. In Project Builder, find the new Should Quit 
event handler stub in Application.applescript, and fill it in with 
Listing 2. Note that tlie Should Quit handler returns true; this is 
necessary in any ‘'should" event handler, to make sure the 
impending action is carried out (a return value of false amounts 
to a veto), 

listing 2 

on should sjuit theObject 

“ Ck'ans up when tJic ;ippllcation is alxnit id quit. 

- Connefied to Rle's Owner in MainMenu.nib 

- Reiniliali/e rdcrefiee to Fretcrenees windtiw for next laurudr 

loadPreferencesControllerLlb 0 

tell preffiControllerLib to celnitO 

return true 
end should quit 

The new Should Quit event handler invokes a relnitO 
handler, which must now be added to the 
preferencesControllerLib script object in 

PreferencesController.applescript, in accordance with listing 5 

Listing 3 

on relnitO 

set prefsWlndDV to null 
end relnit 

Tliere is a design issue in our preferences system, which we 
will mention only briefly. Our Preferences window is a lull- 
lledged window, not a "panel." Among other things, this means 
that the Preferences window' not only becomes "key" w'hen it is 
in from tmeaning tliat it can receive key.strokes and clicks), hut 
it also liecomes “main" (meaning, among odier things, that it can 
be printed). In your own applications, you may find it desirable 
to implement preferences windows as panels. 

Managlng ™l Doyle Usage Log 

Now that our preferences system is bug free, we can turn 
to the Doyle Usage Log. 

Creating or Opening a Document 

We will start by figuring out liow to create a new document. 
In our preferences system and in all of the initial AppleScript 
Studio example projects, this is done by resorting to 
AppleScript's Read/Write commands, implemented in the 
Standard Additions scripting addition. Anybody who ha.s parsed 
out the example projects will realize that this technique is quite 
limited. It fails to take advantage of the veiy^ sophisticated 


document-handling mechanisms buUt into Cocoa. This was 
acceptable for our preferences system, because we stored the 
Doyle preferences file in a fixed location under a fixed name, in 
the context of a normal document, however^ we would have to 
write our own sheets and alerts using AppleScript Studio's 
Display Dialog (or, in AppleScript Studio LI, its Display) and 
Display Panel commands. There is a convenieni way to let 
Cocoa do this work For yt}u, and the principal point of this article 
is to show you how. 

In our preferences system, we gave the user a way to create 
a new document by connecting an event handler to the 
Preferences menu item in the Application menu. We might be 
tempted to start here the same way, connecting the Choose 
Menu Item event handler to the New menu item in the File 
menu. However, if you look at the File menu after compiling and 
running the unmodified AppleScript Document-based 
Application template, you will find that it is not grayed out, or 
disabled, as the Preferences menu item was. I'he reason for this 
is that the template has already connected the New menu item 
for you. You can see this by selecting the New' menu item in 
MainMenu.nib, then selecting the Connections pane (not the 
AppleScript pane) in the NSMenultem Info panel. You see that 
the target of this menu item is CocoabuilLin new'Document: 
action metht>d, which creates a new', empty document for you. 
You may recall that you already saw tliis connection at work in 
tlie previous article, when you compiled and ran the unmodified 
template and .saw that you could already use the New menu item 
to open an untitled document window^ based on the 
Document.nib file provided to you as part of the template. 

Tile same is true of all the other standard menu items in the 
template that you will use in this series. Open, Open Recent, 
SaA C, and Save As are all connected to an appropriate builirin 
Cocoa action method. 

Apparently, therefore, all we have to do is to capture the 
right event handler when one of these Cocoa action methods is 
invoked by the user's choosing the corresponding menu item. 
We wall find, once we get this w'orking, that w^e can use all of 
the built-in document-handling mechanisms of Cocoa to read 
and write our documents, without making any use of 
AppleScript’s Read/Wriie commands. 

To make the New- menu item work, we w'ill configure the 
empty Document.applescript script provided l^y the template 
as our MVC Controller script for this document, and we will 
implement our menu item event handlers in it. Later, we will 
create a separate DocumentModeLapplescript file to act as the 
Mode) .script that manages our document’s data. Notice that 
the Controller, Doeument.applescript, is not named 
'■DocuniemController.applescTipt.” You could give it this name 
if you wish, but it is common in Cocoa to find controller 
classes that don't have the word “Controller" in their names— 
such as NSDocument itself, which generally acts as a 
document controller. 

With the Files Owmer icon selected in tlie MainMenu.nib 
window^ in Interface Builder, select the Attributes pane in the 
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OmniObjectMeter has not been tested on blowfish 
allergies, but it is the best tool to help you seek and 
destroy memory leaks and expensive allocation 
operations in your Cocoa programs. 

• Track allocations, references, and deallocations of 
Objective-C, CoreFoundation, and BSD objects in a 
running process. 

• Use our unique matching window to quickly match and 
hide paired reference count changing events. All that 
will be left are leaks, zombies, and retain cycles, 

• Track down and eliminate transient objects, excessive 
autoreleases, and other inefficient operations. 
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^^ierabyte Macs? 


- But wait, 

OMNIGRAFFLE 2.0 


there's more - 

w/OMNIOUTLINER 2.0 


Our symbolic drawing application easily generates flow charts, ER models, 
network diagrams* and much more. We think it*s the bee's knees. And 
being the overachieving developers that we are, we went and added some 
cool features to OmniCraffle that make our programming lives easier. Now 
with 2.0 we're sharing them with the world, so your life will be easier too. 
Aren't we just peachy that way? 

Project Builder / Framework Import: drag in a Cocoa 
project or framework to automatically create a class 
hierarchy diagram with clickable links to header flies. 

AppleScript Everywhere : use OmniCrafOe as an 
interface for tasks like bug tracking and scheduling. 

Attach scripts to graphics to make Interaaive documents; 
import and layout data from scriptable applications like 
FileMaker. 



OmniOutliner is a general-purpose outlining and list¬ 
making program: we've found it has myriad uses in 
software development: bug lists, project schedules, 
pseudocode outlines, etc, Pius a 
few features Just for geeks like us; 

"Sample" Import; presents output from 
Apple’s command-line "sample" program 
(a useful performance monitoring tool) In 
an easy-to-read hierarchical view, (just 
remove the “.txr extension from the 
output file and open it in OmniOutliner.) 


More AppleScript: 2.0 adds complete AppleScript support, so, for 
example, you can dump your project schedule to OmniCraffle. 



If you've bough! a Power Mac or PowerBook since January 2002, you're already sitting In the back nf the bus with the cool ktds — OmnICraffte 1.1 and OmniOutliner L.Z are already 
Installed In your Applications folder. Bui drop by our website and upgrade to the 2.0 versions we talk about here! they're much cooler. 
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File’s Owner Info panel You will see that the nib file's owner is 
the Document class that is provided as part of the AppleScript 
Document-based Application template, in the form of the 
Documem.h header file and the Documeni.m source file that 
you see in the Classes group in the Groups & Files pane of the 
main Project Builder window for the Doyle application. If you 
click on Document.m and read it, you will see that it contains 
some Objective-C code implementing a few Cocoa methods 
apparently having to do with reading and writing document 
data. You, as an AppieScripter, needn't understand this code, 
and you normally shouldn't edit it unless you are also a 
knowledgeable Cocoa developer. Later, however, we will help 
you make some changes to these files to implement Cocoa's 
document mechanisms for tlie Doyle application. 

Now switch to the Connections pane of the File's Owner 
Info panel, and you will see that the window outlet of the 
Document class is an NSWindow object named "'Doyle Usage 
Log." This is your window, which you creaied in the previous 
article. You are zeroing in on the spot where you can begin to 
write some AppleScript statements. 

Select the AppleScript pane of the File’s Owner Info panel, 
and you w ill see only one event handler, Will Open, under the 
documeni category. Check its checkbox, and check 
Document.applescript, our controller .script, then click the Edit 
Script button. Switch to Project Builder and select 
Document.applescript, You find that a Will Open event handier 
stub has been added, just waiting for you to edit it. 

You already have a pretty good idea of w'hat you have to 
do with this event handler, from your work w ith the preferences 
Controller script. You will need to update the table view' in the 
Doyle Usage Log window' to reflect either the default tlata of a 
new document or the retrieved data of an existing document, 
then make the window^ visible. Before you can do this, however, 
we must turn to the MVC Model script and implement our data 
management routines. 

Managing the Document's Data 

The first step is to create a new- DocumentModel.applescTipt 
script in Projea Builder, and to populate it with properties and 
primitive handlers suita[>ie to hold and manipulate tlic Doyle 
Usage Log data. 

Before doing this, we should develop a clearer sen.se of 
how^ the log will be employed by our typical customer. Recall 
that tJiis is an investigative tool for Sir Arthurs characters, 
Holmes, Watson, and tJieir assistants. Withi>ui try ing to be tiverly 
practical about it, let’s assume that a new' log wall be created for 
each aspect of the inve.stigation. We will therefore need to 
provide for multiple documents, each fclkiwang the user 
interface design that we have already created. Investigators will 
be able to create a new log every lime they want to start logging 
their work on a new^ lead, and they wall he able to save it under 
a descriptive name — "*Dog Didn’t Bark," say. Each time a 
particular log is opened, the log file will automatically be 


updated to show the date and the nature of the action — and, 
depending on the preference settings, allow' the user to view, 
enter, and edit comments for each entry. 

In the previous article, we indicated that a log entry w^ould 
be created whenever die Doyle application is launched or quit, 
but we have reconsidered in favor of this multi-document 
approach. Because the investigative team will be able to open 
multiple documenrs for various leads, noting when each 
document is opened will serve the same purpose as noting 
when the application was launched in the original specification. 

To create the new script file in Project Builder. Choose 
File -> New. In the New File Assistant, select AppleScript File 
and click Next. In the New AppleScdpi File Assistant, name it 
'^DocumentMtKleLapplescripi" and ensure that it will be added 
to the Doyle Project and will target the Doyle application, then 
click Finish. Type the entire contents of this new script file 
from Listing 4 

Listing 4 

C r>t>aimcniMtHfel.appl<!stTipt -) 

C'Hiis is an MVC McmIlI script iliai manages the data sitircd in a dnenmenc li 
prEJvidcs an initialization handler and go ;ind set accessor handlers for the 
eniire doaimeni tiata sttvre.and get and set accessor handlers for indkidual 
data entries, as weJl as wme uUlitV' hanUlens. 

Tile value of the data store is set to empt}' in the iniiDatatJ handler, which 
is cxecnied only when a new' dotumcnl is created. Otherwise, the Values of all 
data iiencs are a^ad from the dticiimeni and held in an AppleScript property 
in the getDataO handler, and saved fnint the propeuy back to the document in 
the selDataO handler,The AppleScript kjgllataStcjrx' pniperty in this script is 
associated wiUi the dataSLiiit' instaoee variable declared in tile Uoeiimejlt 
subclass of the NSDixurneni Ctx:oa dass. by m:iking some custom Objective-C 
m<Hlifications to the default Oixunicnt class provided by the AppleScript 
l)(Krumeni-based AppljcaUcm template. Data values aie held and managed in this 
script as a single AppleScript List, and in the iJtxument object as a single 
Cocoa NSString objec't, It isn't necessarv to maintain dual data stores in 
ihi.s manner, Lnsiead, you could write all of these handlers to deal directly 
with die doctinient's daniSLore instance varuibie.We maintain a separate 
AppleScript list prriperry' here for darit)'. anil to show how it can be done 
in ease you want to maintain your data in multiple separate AppleScript 
pn^perties. Error diecking Is omitted. 

(* Pniperties *) 

property logDataStore : I ] 

C Script (.Objects *) 
script docujBentModelLib 
Handlers *) 

“These handlers provide access to document values at the most primitive level. 

- Load this script t>bject into another script and call these primitive handlers 

- whenever access to dixurnent values is required. If the document infrastructure 

- Ls later changed, only tJiis scripi will require revisjon, iio long as the 

- names, parameters, and return values of these hsindJers remain unchanged (i.e., 

- each data entry' is a threeitem list). 

on InitData (theDocuinent) 

- Initializes data values; called only if no document file exists yet. 

“ initialise instance variable daiaStore of Dtxtiment object to empty string 
call method “aEthataStore:” ^ 

of Object theDocuinent with parameter 

- initialize property logDataStore of thb script to empty AppleScript list 
set logDataStore to I) 
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end InitData 

on getDflta(theDocmiient) 

- Ctts dm vaJues from Document object into script property. 

“ (rt-'i talHiclimited string fnjm insuuice variable dataStore of Documeni objea 
set tbeStting to call method ^'dataStoce" 
of object theDocument 

- Set property logDaiaStore of this script to the string as AppleScript list 
set oldDeiims to AppleScript*s text Item delimiters 
-- save old delimiters 

set AppleScript's text item delimiters to ftabi 
set logDataStote to text items of tbeString 
-- convert string to list 

set AppleScript's text item delimiters to OldDeiims 
-- restore old delimitErs 

return logDataStore as list 
end getData 

on setData(theDocument) 

” Sets data values in Document object fttjm script propertv 

“ Ciet tab-delimited byte stream from property logDataStore of tiis script 
set oldDeiims to AppleScript's text item delimiters 

- - save old delimitGrB 

set AppleScript's text item delimiters to Itahf 
set theString to {logDataStore as string) 

-- convert list to string 

set AppleScript’s text item delimiters to oldDeiims 
-- restore old delimiters 

- Set instance variable dataSiore of Document object to result 
call method “setDataStore:" “> 

of object theDocument with parameter theString 
SCI modified of thefhKumoit to tnie 

- so Cocoa will know it needs to be saved; 

- when it Ls saved, Cocoa wilJ automatically reset modified to felse 
end setData 

on appendlDataEntry(entry. theDocument] 

- Adds a data entry to the end of the list, 
set end of logDataStore to entry 
setData(theDocument) 

end appendlDataEntry 

on setlDataEntry(entry.Num^ entry, theDocument} 

Replaces the data entry at entry entryNum. 
set idx to (entryHum * 3} - 2 -- AppleScript lists are 

L-based 

tell logDataStore 

set item idx to item 1 of entry 
set item (idx + 1) to item 2 of entry 

set item (idx + 2) to item 3 of entry 

end tell 

BetData(theDocument) 
end setlDataEntry 

on removelEataEntry [entryMuiUj theDocument) 

” removes the data entry at entry entryNum, 

set idx to (entryNum * 3} - 2 ■- AppleScript lists are 

1'based 

if length of logDataStore is 3 then 

- remove only entry' in list 
set logDataStore to {\ 

else if idx is equal to 1 then 
~ remove first entry in list 
set logDataStore to items 4 thru 

(length of logDataStore] of logDataStore. 
else if idx is equal to ^ 

((length of logDataStore) - 2) then 

” remove last entry in list 

set logDataStore to items L thru “* 

(idx - I) of logDataStore 

else 

- remove entry between first and last entries in list 
set logDataStore to Items 1 thru 

(Idx - 1) of logDataStore h ^ 
items (idx + 3) thru 

(length of logDataStore) of logDataStore 
end if 
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setData (thEDocmnent) 
end reaiovslDataEntry 

on getlDataEntry(entryNum, theDocmnent) 

- Returns ojirent value of the data entry at entry entryNum. 
set idx to {entryNum * 3) - 2 -- AppleScript lists are 
l-based 

getData(theDoc ument) 

tell logDataStore to return ^ 

Iitera idXt item (Idx + 1)» Item (Idx + 2)] 
end getlBataEntry 

end script 

The basic strategy^ of the DocumentModel.applescnpi 
script is very similar to that of the PreferencesMcxiel.applescnpt 
we developed in the previous article. An AppleScript property 
is defined to hold the data, and a script object containing 
several primitive data handlers is defined, ready to be loaded 
into the Document,applescripl Controller script when we get 
around to writing it. 

Here, however, the data is not a single Boolean value, as it 
was in the preferences Model script, but a succession of values 
recorded in the table view you created in the previous article: 
tliat is, an open-ended succession of log entries, each consisting 
of the date, the nature of the action, and some comments. An 
AppleSeripier would be tempted to implement this data staicture 
as a list of AppleScript records, but for simplicity's sake we will 
use a simple, Hat AppleScript list, instead. We know tliat each Log 
entry contains tliree items, so we will write our Mtxlel script to 
treat every third list item as the beginning of a new log entry. 
This list will be held in an AppleScript property, logDataStore. 
Given your experience with the primitive data handlers in 
PreferencesModeLapplescripi last time, you will have little 
difficulty parsing out the function of each primitive data handler 
in Listing 4, Each handler simply manipulates the list value held 
in the logDataStore property', getting, .setting, adding, and 
removing log entrie.s. Each of the handlers that manipulates the 
value of a single log entry' uses a more general handler, 
getDalaC) or setDataO, to obtain or update the entire li.st. This is 
every-day AppleScript list-handling code. 

But wail a minute! What are those Call Method statements 
doing in the initDataO, getDataO, and setDataO handlers? 
These, my dear colleague, are the keys to the mystery we 
presented to Sir Arthur in the previous article. Nowhere in the 
existing AppleScript Studio documentation or examples can we 
find a solution to the problem of using Cocoa’s built-in 
document-handling mechanisms. Now, we will solve the 
mystery' ourselves and conclude the investigation. It involves 
writing some Objective-C metliods in the DocumenL object 
provided by the AppleScript Document-based Application 
template, and using the AppleScript Studio Call Method 
AppleScript command to execute them. 

All of the other dati liandler.s in DcKumenlModeLappiescripl 
get, set, add, and remove entries from the Doyle Usage Log by 
manipulating the global logDataStore AppleScript list pn^peity we 
added to DocumentModelappJe.script. But the initDataO, 
gelDataO, and selDataC) handlers do more than that — they also 


read and write die entire AppleScript list from and to the document 
object as a byte stream, via the Call Method statements. 

Call Method is an AppleScript Studio command that 
enables a script to call an Objective-C Cocoa method, passing 
parameters to it as needed and retrieving any returned value. 
To take advantage of the built-in Cocoa mechanisms for 
reading and writing documents, we must write a small number 
of lines of Objective-C code. You will not need to know 
anything about Ohjeciive-C to do this, liecause we will do it Ibr 
you and describe it briefly. If you choose to use this teclinique 
in your own applications, you can simply copy our code from 
the Document Ji and Document.m files in the Classes group in 
the Groups & Files pane of the main project window. This is 
fully reusable code. 

The Document class's header and source code are shown in 
llsting,<i 5 and 6, respectively, 

listing 5 
// Document.h 

liiraport (Cotoa/Cocoa.h> 

^Interface Docutnant : NSDocument 

1 

NSString *dataStere: 

I 

- (KSString *)dataStore: 

- (void)setDataStore:(NSStrlng *)data: 

@end 

Listing 6 

// Dociimtni.m 
ffiraport “Document.h'' 

SimplemeTitation Document 

- (HSStting *)wlndowMlbNaine 

I 

//1 rndiingcd frum AppleScript Docoment-bascd Application template 
return @”DDcaiiient": 

] 

- (void) windovControilerMdLoadNl b: 

(NSWindowController *)aContro11er 

I 

// I fndianged from AppleScript Document-based Application template 
[super wlndowControllerDldLoadNibjaController); 

I 

- (NSData *)dataRepresentationOfType:(NSString GaType 
I 

U (iei ilataSttitc NSSiring object and send tcj |)crsistem storage as NSData object, 
return [[self dataStore] 

dataUsingEncod1ng:NSUTFBS t ringEncoding]: 

\ 

- (BOOL)loadDataRepresentation: 

(NSData ‘)data ofType: (NSString G aType 

f 

// Receive NSI^ta object from persistent storage and set dataStt^rc as NSString object. 
NSString *tenip - [[NSString alloc] inltWithData:data 
encoding: NSDTFBStrlngEncodirig] \ 

(self setDataStore;temp] ; 

[temp release]: 
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return YES; 


) 

// Lnit and dtaUcjc mctfuxJs 

- [id)init 

I 

//Allocate and initialize daiaStonf as an empty NSString object, 
if (self = [super init]) E 

dataStore ^ [[NSString alloc] lnit]: 

[ 

return self: 

1 

- {void]dealloc 
[ 

// Deallocate the dataStore NSString object. 

[dataStore release]: 

[super dealloc]: 

I 

// tlataStore accessor methods 

- (NSString *)dataStore 

I 

// Reivim dataStore NSString object, 
return dataStore: 

I 

- (voidjsetDataStore:(NSString ’)string 
[ 

if Set dataStore NSString object to value of data parameter. 
[dataStore autorelaase]; 
dataStore = [string retain]: 


@end 

Our basic strategy is lo create a single so-called '‘instance 
variable” in the Document class’s header file, which will be used 
to hold tlie logDataStore list in the form of a tab-delimited string, 
or byte stream. Using two Objective-C “accessor metliods”— 
setDataStore: to set the value of the document’s instance variable 
and dataStore to gel it—you will be able to read and write any 
AppleScript string nr text value using the Call Method command 
to execute either of these two accessor methods. You won't 


need to change the Objective-C code if you define some 
different AppleScript data types in your application, because you 
c'an convert your data between its AppleScript form and a tab- 
delimited string in your AppleScript files using the techniques 
shown in DocumentModel.applescript. 

The header tile simply declares the instance variable and 
the two accessor methods. 1'he source file is more interesting. 
You already know from the previous article that the AppleScript 
Document-based Application template contains a very small 
amount of pre-written Objective-C code. In fact, this is the same 
pre-wriiten code that is used to build any Cocoa document- 
based application. The first two cjf tlie supplied methods are of 
no interest to us (don’t remove them from the Document.m file, 
though), but the other two require slight modification to make 
our scheme work. In addition, of course, we must write the 
implementations of our two accessor methods and some Cocoa 
memory management code. 

The supplied dataHepresentatianOfType: method must 
return our document's data as a byte stream, known in Cocoa 
circles as an NSData object. We will write this method so that it 
returns our instance variable, but we will never call this method 
ourselves. Instead, Cocoa calls it automatically when the Cocoa 
action methods connected to the Save and Save As menu items 
are invoked. By returning our instance variable as a byte stream 
in this method, we have, in a single line of Objective-C code, 
enabled our application to write its data to disk. 

Similarly, the supplied loadDataRepresentation:ofType: 
method must assign to our instance variable the data that Cocoa 
reads from disk when the action method connected to the Open 
and Open Recent menu items is called, and return YES to 
indicate success. Never mind the mysterious Objective-C and 
Cocoa commands you see in these methods, such as alloc and 
release. This is Cocoa memory management code, which an 
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AppleScripter doesn't need to understand until deciding to learn 
Cocoa. The same goes for the simple init and dealloc methods 
that are implemented in Documeni.m and called automatically 
by Cocoa at appropriate times. 

Finally, the dataStore and setDataStore: accessor methods 
are quite simple. Apart from the memory management code, 
these simply get and set the value of the instance variable. You 
may have noticed that the instance variable is declared as a 
Cocoa NSString object in Document^h* We do it this way 
because AppleScript Studio can move seamlessly between 
AppleScript strings and Cocoa NSString objects, allowing you to 
pass AppleScript strings to and from Cocoa by using these 
accessor methods in Call Metftod statements. Because Cocoa 
mandates that the dataEepresentatlonOfType: and 
loadDataRepresentationiofType: methods must work with 
NSData objects, our code in those two methods converts 
l)etween NSData and NSString types using Cocoa melhiids 
designed for the purpo.se. 

The technique we use in DocomentModel.applescript to 
convert between the tab-delimited string held in the Cocoa 
Document object and the AppleScript list property we defined 
in DocumenlModeLapplescripL deserves brief mentinn. 
AppleScript provides a mechanism, known as the text item 
delimiter (TID), lo break a string into a multiple-item list, and 
to built a multi-item list hack into a string, very rapidly. We 
therefore set AppleScript's text item delimiter temporarily to 
an ASCII horizontal tab character, then either get the multiple 
text items c^f a tab-delimited .string retrieved from the 
Document object, or gel the string by converting the 
AppleScript property using AppleScript's As Siring coercion. 
We save AppleScript’s existing text item delimiter and restore 
it at the end of the conversion, to maintain a knowm baseline 
in case other routines rely on the text item delimiter 
remaining unchanged (this step is not mandatory but is very 
commonly used in AppleScript). 

With about a dozen lines of Objective-C code and some 
AppleScript support, we have created a reusable custom 
Document class that wall allow' any AppleScript Studio 
application to save information to disk and retrieve it from disk 
using Cocoa’s biiilt-m mechanisms and the existing menu items 
implemented in the AppleScript Document-based Application 
template. All of the disk navigation sheets for .selecting a name 
and location under which to save the data are provided 
automatically by CtK'oa, along with Aqua-compliant sheets for 
opening a file you have saved. In addition, for free, you get 
alerts for handling name collisions and duplicates, for dealing 
wath multiple unsaved files w'hen the Luser quits the application, 
and so on. You don’t have to sjsend any time dealing cviih the 
AppleScript Read/Write commands or writing your own sheets 
and alerts using AppleScript Studio’s Display Panel and similar 
commands. At the small cost of getting comJ'ortable w ith a little 
Objective-C code, you have avoided a significant amount of 


work and created a much more powerful and .standards- 
compliant application. 

Updadttg the Documents User Interfece 

With our primitive data management handlers and their 
Cocoa support routines in place, we can now return to 
Docurnent.applescript to coordinate a Doyle document's data 
with the user interface. Again, the strategy is similar to what we 
did with the preferences Controller script. We declare a property 
to hold the script object defined in DocumentModel.applescript 
and a loadDocumentModelLibO handler to load it, and a similar 
property and handler to get at the preference value managed by 
PreferencesModel.applescript. We also define a script object 
containing high-level counterpans of the primitive document 
data handlers. Although these will only be used within 
Document.applescripi itself and therefore don’t have to be 
wrapped in a script object, we place them in a script object in 
ease we miglit want to load them into some other script as a 
future enhancement. Finally, w'e implement some utility handlers 
and event handlers to deal with the user interface w'hen the user 
creates new documents, opens existing documents, and saves 
changes to disk. See Listing 7. 

Listing 7 

C DtK iinicnLappltscript") 

<*Ttiis Is in M VC Gjntrollcr script tonuiining li^idlcrs to ctiordinaie data 
vyJucs in DtxrumentMotkl.applescript with thf user interface in the main 
diHrumcnt window. It di>e 5 this for the Windows's tjabte view by manipulsbng 
the table view’s as.sociated data soince oliiecb wliich is connected to the 
window in Interface Builder.The data stnirce object is manipulated here^ 
in the tlocumetit s Controller script, becausti the diUa stiurce is a 
view-related ol^jeet. not to be confused witli the document's data store 
instance variable, which is manipulated in L>{x:umeniModel.applescript.an 
MVC MtHJel script.') 

t* lYo[)efties *> 

property logModelLib ^ null 
property prefsModelLlb : null 

property vindovLlst : I ] 

- list of records asstxiating documents with their windows by ID 
<* Scri]>l Objecis *) 

script docujiientControllerLib 

-lliese Ijiindiers arc placed in a script object Ln case future 

- enhancement cjf the application requires that they he loaded 

- into anotlier script. 

Handlers'f 

‘Tliesc hiuidiers manipulate a documeni's data usinj* plsiin English 

- lerminolog)', by loading and calling the primitive data handlers 

- in DocumentModeLapplescTjpt. If the document infraslrtieluit in 

- DocumentModel.applescTipi is later changed, tins script will not 

- require revision, so long as the names, parameters, :md return 

- values of the primitive data handlers rem;iin unchanged (i.e„ 

- each lug cnirv* is a tha'e-iiem list). 

on initLog(theDccument) 
loadDocunentModelLlh {) 

tell logModelLlb to inltOata(theDoemnent) 
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end InitLog 

on getLog(theDocument) 
loadDocumentModelLib() 

tell logModelLib to return getData(theDocument) 
end getLog 

on setLog{thel)ocuTiient) 
loadDocumentModelLlb() 
tell logHodelLib to setDataCtbeDocument] 
end setLog 

on addLogEntryAtEndCentry» tbeDocunient) 
InadDocumentModeXLib() 
tell logModelLih to 

append 1Dat aEnt ry(ent ry. theDocument) 
end addLogEntryAtEnd 

on replaceiLogEntryAt (idjc, eiitry» theDocument) 
loadDocumentModelLib() 
tell IqgModelLib to 

setlDfltaEntry [idx, entry* theDoctiMent] 
end replaceLogEntryAt 

on temoveLogEntryAt(Idx* theDocument) 
loadDocumentModelLib 0 
tell logHodelLib to "> 

removeIDataEntry (Idx. theDocunient) 
end removeLogEntryAt 

on getLogEntryAt(idx. theDocument) 
loadDoeumentModelLib() 
tell logModelLlb to ^ 

return getlDataEntry(idx. theDocument) 
end getLogEntryAt 

end script 

c Handlers *) 

on loadDocumentHodellibO 

- Loads documeniMotlelLih from lltJCumenLModel.itpplescript. 

- if not airieatV loaded . 

if class of JogModelLib is not script then 
load script PQSIX file -f 

(path for main bundle script 
""DocumentModer' ejetension "'acpt’") 
set logHodelLib to documentModelLlb of result 
end if 

end loadDocutdentModelLib 

on loadPreferencesHodelLib() 

- Loads PreferencesModellih frt>m IWercncesModtI.applescript. 

-- if riot already loadtxl. 

if class of prefsHodelLlb is not script then 
load script POSIX file (path for main bundle ”• 
script ‘•PreferencesHodel" extension “sept”) 
set prefsModelLib to preferencesModelLib of result 
end if 

end loadPreferencesModelLib 

on InitDataSource(theWindow) 

- C^reates daiii ctd iimns in the dati souree 
^<if the table view loaded from Document.nib. 
tell data source of table view “Log'* 

of scroll view “Log’" of theWlndow 
make new data column at_end of data columns “> 
with properties [name:"date""] 
make new data column at end of data columns 
with properties f name:’’action*’I 
make new data, column at end of data columns ^ 
with properties fname:“comments'" 1 
end tell 

end initCataSource 

on upd ateDataSourc eOnOpen(theWindow) 

- Updates the data source of the table view loaded from 

- OtKiimeninib wlicn the Window opens (whether on a new or 

- existing document). Tliis automatically updates the 

- contents of the table view on screen. 

set theDocument to getDocumentforWindowttheWindow) 


tell documentControlIerLib to getLog(theDocument) 
set theLog to result 

repeat with idx from 1 to length of theLog by S 

-The log has at least one entry (3 list Items). 

- because we set up tlie first enirj' in the Will 

- Open event handler when the document opened, 
set entryNum to {Idx div 3) + 1 

-AppleScript lists art 1-ljased 
tell documentControlIerLib to 

getLogEntryAt(entryNum* theDocument) 
set theEntry to result 
tell data source of table view “Log” 
of scroll view '"Log" of theWindow 
set theRow to make new data row at end of data rows 
set contents of data ceil “date" of theRow to 
item 1 of theEntry 

set contents of data cell "action” of theRow to 
item 2 of theEntry 

set contents of data cell "cominents" of theRow to “> 
item 3 of theEntry 
end tell 
end repeat 

end updateDataSourceOnOpen 

□n getDocumentForVindow(theWindow) 

- Refiims the document object associated wltli tlieWindow in windowlist. 
repeat with idx from 1 to length of windowLlst 

if wlnlD of item idx of wlndowList is equal to “> 

Id of theWindow then 

return document id (docID of item idx of windowList) 
end if 
end repeat 
return null 

nt) assfxnated window found (fdicmldn’t gel here) 
end getDocumentForWindow 

on removeFromWindowLlst{theWindow) 

- Remove^i the windtiw from windowlist 

repeat with idx from length of wlndowList to 1 by -I 

- ill ways remove fn>m list backwards for correct indices 

if winID of Item Idx of windowLlst is equal to 
id of theWindow then 
if length of windowLlst is 1 then 

- remove only record In list 
set wlndowList to f| 

else if Idx Is equal to 1 then 

- remove first record hi list 

set windowLlst to rest of wlndowList 
else if idx is equal to length of vindowList then 

- remove last record in list 

set windowLlst to items 1 thru 

(tlength of windowlist) - 1) of wlndowList 

else 

- remove record between first and last records in list 
set windowLlst to items 1 thru ^ 

[idx - 1] of wlndowList ^ "« 
items (Idx + 1) thru (length of windowLlst) 
of windowLlst 

end if 
end if 
end repeat 

end removeFromWindowList 
(‘ Event Handlers *) 

on will open theObJect 

- Initlahzes a new document or gets data stored in an existing 

' tldciimeni, then appends a new automatic log entry then u|x)ates 

- the data source to set the vT.sual state of the windtjw to match ^ 

- and makes the wind<w visible. Also adds document and window to 

- windowlist property fi>r later looku|5. Connected to the document 

- (File’s Owner) and window tobjects in Dix^ument.nib. 
if class of theOhject is document then 

-llie document object opens before the window object opens, 

^Tlie doaiment's nib file is automatically loaded by Cocoa, 
get windows whose visible is true 
if result is I] then set windowLlst to tJ 
set end of windowlist to 

twinID:0, docID:id of theObjectI 
if file name of theObject exists then 

- Standard tecimique to determine whether 

- exbliiig dotiimeiu b lieing opened. 
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tell documentControllerLib to getLog(theObject) 
set the Action Item, to "Open" 
else 

- Heiiv document is being aeated. 

tell documentControllerLib to initLog(theObJect] 
set theActlonltem to “New" 
end if 

get current date 

get date string of result St space ii “> 

Time string of result 

set theEntry to I result, theActionltem^ '"’1 
tell docuiaentControllerLib to 

addLogEnt ryAtEnd(theEnt ry, theObj ect) 
else If class of theObject is window and 
name of theObJect is "Log’’ then 
-The window object tjpens after the document object opens, 
set winID of last iteto of windowList to Id of theObject 
initDataSource(theObject] 
updatebataSourceOnOpen(theObject) 

- Hide (Xsmments column acconUng to preference 
loadPreferencesHodelLlb{) 

tell prefsModelLib to getShowComnientsPreferenceO 
if result is false then 

set theCol to table column “comments" of ^ 

table view "Log" of scroll view "Log" of theObject 
set editable of theCol to false 
set width of theCol to 0 
end if 

set enabled of button "Delete" of theObject to false 
set visible of theObject to true 
end If 

end wil] open 

on will close theObject 

- Removes window from windowUsi; prsijierty when window is 

- dosed. (Connected to ihe window ohjeci in Documcni.nib. 
if class of theObject is window and 

name of theObject is "Log" then 
removeFromWindawList (theObject) 
end if 

end will close 

on should selection change theObject 

- Commits edited Comments when user dicks or l;d>s out of 

- cell or presses Enter or Reiunt Clonnected to the tsibie 

- view object in Docnnteni.niEy. 

If (class of theObject Is table view) and ^ 

(name of theObject Is "Log”) then 
get window of theObject 

set theDocument to getDocumentFDrWindov(resultJ 
set rowNum to selected row of theOhject 

- row number beibre seiection dninges 
if rowNum ) 0 then 

- some TOW is selecled.and |>{wsihiy is being edited 
tell. documentGontroJ lerLlb to 

getLogEntryAt(rowNum, theDocument) 
set theEntry to result 

- old cell v:due 

get contents of data cell '’comments" of “i 
data row rowNum of data source of theObject 

- new cdE vyiiic 

if theEntry is not equal to result then 
- replace only if old and new cell values are differeni 
set item 1 of theEntry to result 
tell documentControllerLib to 

replaceLogEntryAt(rowNum. theEntty, theDocument) 
end if 
end if 
end if 
return true 

end should selection change 

on selection changed theObject 

- Changes ertabled state of Delete btktton when row of table 

- view is selected or deselected. i/>nnecled to the tabic 

- view object in Document .nib. 

If class of theObject is table view and 
name of theObject is "Log" then 
if selected row of theObject is 0 then 

- no row IS seiected 


set enabled of button "Delete" of window of 
theObject to false 

else 

- a rt>w is selccEed 

set enabled of button "Delete" of window of 
theObject to true 
end if 
end if 

end selection changed 

on clicked theObject 

Deletes selected row when Delete button is clicked. 

- Connected to Delete button object in Document.nib. 
if theObject is equal to button "Delete" of 
main window then 

set theTableView to table view "Log" of “■ 
scroll view "Log"' of main window 
set rowNum to selected row of theTableView 
if rowNum > 0 then 

- St) me row is selected 

delete data row rowHum of data source of theTableView 
ray getDocumentForW.lndow(window of theTableView) 
tell documentControllerLlb to 

removeLogEntryAt(rowNum, result) 
end if 
end if 
end clicked 

Most of the handlers in Dociiment.ai^plescript deal with 
the table view that w^e designed in Intertace Builder in the 
previous article. Becau.se table views are covered quite 
thoroughly in the AppleScript Studio documentation and 
examples, we will not explain all the details liere. 

In summary, we use Interface Ikiiklcr to connect an event 
handler that responds to the user's opening a document and 
opening a window; namely, the Will Open event handler. 
When I he user eliooses the New' or Open menu item or a 
document from the Open Recent menu item, a Will Open 
even I announces the creation of the d{)cumem object, first, 
then a second Will Open event annotmees the opening of the 
document’s associated window object. We use If tests to 
distinguish between these two events, taking care ol creating 
rite data for a new' automatic log entry when the document 
object is created, in accordance whth our application 
specification, and updating the data ,source object to display 
this data wlien the window object opens. The data source 
object, which eomrols the appearance of data in the table 
view, is adec|Liately covered in ihe documentation and 
example projects. The final step, of course, is to make the 
window visible—Coeem loads the nib file automatically in a 
document'based application. 

We use Interface Builder to connect the Will Close event 
handler for the .sole purpose of removing the window's record 
from a window list that we maintain to associate each document 
with its window. We set up a new entry in this list in the Will 
Open handler, getting ihe ID of each document and each 
window as they are opened. The getDocumenlForWindowK) 
utility liandler allows us to get the document that is associated 
w'iih any given document window using this list. The 
renioveFrtanWindow'ListO utility^ handler called from the Will 
Close event handler .simply removes the closing window' s 
record from the list, using standard AppleScript code for 
removing an item from a li.st. 
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The next step is very significant. We use Interface Builder 
to connect the Should Selection Change event handler to the 
table view in the window. This is critical, as it allows us to 
write an AppleScript Studio application in which a user can 
edit individual items of a table view in place. The AppleScript 
Studio example projects instead use the awkward technique of 
requiring a user to type information into a series of separate 
text fields, then setting eacli cell in the table view to a value 
shown in the corresponding text field by the use of 
AppleScript statements. Cocoa allows you to edit cells of a 
table view directly, in place, by double-clicking on a cell to 
select it for editing, then typing, then clicking or tabbing out 
of it or pressing Enter or Return to commit the new' value. The 
importance of the Should Selection Change event handler is 
that it captures the very user actions which, under the Aqua 
Human Intt/rface Guidelines, signal the user’s intent to 
commit the data in an edited cell. This enables us to grab the 
new data in a cell of the table the moment the user ^commits” 
the edit; that is, when the user clicks or tabs out of the 
Commenis field or pre.sse.s Return or Enter, If the value in the 
Comments field differs from the value in the data source 
object, we call our high-level handler to replace that log entry 
in DocumeniModel applescript. We return true, of course, in 
order to avoid vetedng the pending action in this "should” 
event handler 

Finally, we use the Should Selection Change and Selection 
Changed event handlers to find out whether a row' in the table 
is being selected or deselected, and to enable or disable our 
Delete button accordingly. Notice that it was disabled in the 
Will Open handler, because we do not select a row 
automatically when a window first opens. The Clicked event 
handler takes care of deleting a row when the user clicks the 
Delete button. 

There is one final element of our document-handling 
routines, necessitated by a bug in the first release of 
AppleScript Studio. Although all of the routines described 
above work when the user sets out to create a new' document 
or to open an existing document, they crash if the application 
is designed to open a new', empty dcjcumeni on launch—a,s 
every proper Mac OS X application is supposed to do. We 
have not succeeded in finding a workaround, so we will 
disable the creation of a new', empty document when Doyle is 
launched. This is easily done by adding the following event 
handler at the end of the Application.applescript hie that we 
w'rote in the previous article: 

Listing 8 

on should open untitled theObject 

- Suppnesiits opening an empt>^ document at launch 
return false 

end should open untitled 

This bug i.s fixed in AppleScript Studio 1.1, so the 
handler can be removed when Doyle Is built for that 
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environment. Either disconnect the handler in MainMenu.nib, 
or revise it to return true. 

At this point, we have implemented almost all of our 
application specification. The Doyle application's New, Open, 
Open Recent, Save, and Save As menu items work as they 
should to implement the Cocoa document-handling facilities. 
The only remaining task is to honor the preference setting. We 
will turn to that in a moment. 

We haven’t yet described all of the Interface Builder Info 
Panel Attribute settings for the Document.nib file. We will 
summarise them here. The Log window object's Resize 
setting should be turned off, because we haven't 
implemented any of the Interface Builder techniques for 
stretching and shrinking user controls to match the window 
size. The table view object’s Allows Empty Selection setting 
should be turned on, but the Allows Multiple Selection and 
Allows Column Selection settings should be turned off. Also, 
Vertical Scrollbars should be turned on and Horizontal 
Scrollbars should be turned off. The Date and Action table 
column objects' Editable Option should he turned off, while 
the Comments table column objects Editable Option should 
be turned on. Don't forget to provide names for all the 
objects that are controlled via AppleScript, both in the 
Attributes Pane and the AppleScript Pane; these names 
should match those used in the relevant handlers in the 
scripts. The name of an object in the Attributes and 
AppleScript panes should l)e the same. Don't forget to give 
the scroll view^ (click once to .select it) the same name as the 
table view (double-click La select it). 

There are a couple of points we haven't covered. For one 
thing, the Revert menu item doesn’t work right. We will leave 
it to you to fix if you can. For another, haven’t 
implemented any ability to add new' log entries to the table 
once a document window is open, This is a coasequence of 
our application specification, which creates a new^ log entry 
automatically when a new window is opened and not 
otherwise. Adding an ‘"Add" button alongside the existing 
"Delete” button is an ea.sy matter, already covered by one of 
the AppleScript Studio example projects. 

Honoring the Preferences Setting 

Our last task is to ensure that the Comments column is 
not visible in the event the user has deselected the Show 
Comments preference we created in the previous article. We 
do this w'ith a block of AppleScript code in the Will Open 
handler that executes w'henever a window' opens. We load 
PreferencesModel.applescript, if it is not already loaded, and 
get the setting of the preference item. If it is false fi.e., 
unchecked), we make the Comments column of the window 
iineditable and, more to lire point, we set its width to zero to 
effectively hide it from view. This is not a particularly 
aitracLive solution, because the column header is truncated 
imperfectly, but it is the only way we have found to hide a 
table view column. 


Notice that any change to the preference setting takes 
effect only with respect to windows that are opened thereafter, 
Windows that are already open do not change. It is certainly 
possible to write the application so that the Comments column 
W'ill Instantly disappear or reappear the moment the setting is 
changed, but this would involve a lot of additional code that 
isn't needed for this article. 

Conclusion 

In this series of articles, you have been exposed to some 
relatively complex AppleScript code illustrating how to create 
a Cocoa application using AppleScript. We have Ibcused on a 
modest—and somewhat fanciful—application specification in 
order to keep the articles shorter than they would otherwise 
have been, but we have been able to cover many of the 
techniques used in AppleScript Studio and a representative 
sampling of its capabilities. AppleScript Studio’s terminology 
dictionary is extensive, and you can use it to implement just 
about all of the user interface widgets and fimctionaliiy that 
are seen in Mac OS X applications, 

The most important point of these articles is to show that 
it is possible, with only a little custom Objective-C code, to 
make use of built-in cocoa features that have no direct 
counterpart in AppleScript, While AppleScript does 
implement the Kead/Write commands that allow a scripter to 
store and retrieve data, these commands are very simple and 
do not include any of the user interface elements that go 
along with .storing and retrieving data in a fully Aqua- 
compliant application. Not only do you gain the benefit of 
Cocoa's superb user-interface functionality by doing things 
the Cocoa way, instead, but it's actually easier than doing 
things the traditional AppleScript way. 

Compare the Read/Wrile technique we used to store and 
retrieve the preferences settings in the previous article with 
the Cocoa techniques we used to store and retrieve 
document data in this article. Then imagine how much more 
AppleScript code you would have had Uj write if you had 
wanted to let the user store the preference setting in any 
folder under any name. You would have had to write all the 
sheets and alerts that deal with file navigation and name 
collisit>ns yourself. But, using the techniciues taught here for 
the Doyle Usage Log, you never have to go to that trouble 
for any document. 

Similar savings can undoubtedly be achieved in other 
aspects of AppleScript Studio application development. One 
has already been released by Apple informally on the 
AppleScript-Suidio mailing list and appears as a built-in 
feature in AppleScript Studio l.l, allowing the saving and 
retrieval of preference settings using the built in 
NSUserDefaults facility in Cocoa instead of the Read/Write 
commands technique w'e used in the previous article. Othens 
are sure to follow. 
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360^ panoramic image in a single camera shot The system is the 
perfect solution for capturing all the action, as it happens! Years of 
extensive research have produced an innovative solution that 
creates an immersive image without the restrictions or 
compromises normally associated with panoramic photography. 


The 360 One VR is available with a variety of photographic 
accessories. These include: monopods, tripods, bubble levels, camera 
bags and Pelican hard cases. You can purchase them separately or 
together at a discount in either our Pro Accessory or Real Estate Kit for 
the 360 One VR, 

For more information on camera mounting kits and all the latest 
accessories, visit our website, 
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REALBASIC 


By G.D. Warner 

REALbasic: How Do You Learn This 
Stuff, Anyway? 


Suggestions on how one goes about 
teaming to program in REALbasic 


By Way of an iNTROincnoN 

As l\ says in the little box up there, my name is G*D. Warner, 
and I have lieen asked to serv^e as the RFAUrasic Contributing Editor 
for Mat Tech. \ have a few articles plattned, i>ut sc»nie of these will 
take time to develop properly ... so if there's anything you'd like to 
see discussed here, or if you've got an idea, or have written an ^irticle 
you'd like to appear here, then i>y all means shcxit me an e-mail. 

The Heari of the M\iter 

In this, my first official outing as MacTecb^s REALl^asic 
columnist, 1 wiU examine that age-old question every new 
programmer asks, regardless of the language: 

*^How in the worid do \x}U learn this stuff, Anyimy?tF* 

To discover the aaswer to this c]uestion, 1 pt>sted a question on 
some of the newsgrcaips (comp,sys.macprogrammenmisc, and 
comp.lang.basic.realbasic): What is the tx:st way to learn a 

programining language? Tliat is, is it better to read through the 
keywords first, or what?" 

As you might guess, 1 got a k)t of different ansAven>. 

Phillip Stripling sums everything up pretty' well: 

"There isn't a be.st way, and there isn't an eHident way." 

LIh-oh. 

He then explained how he learned: 

"rd also say it depends on the language. I learned BASIC by 
typing in programs and fixing my ty^pos. I didn't read books on 
programming BASIC until 1 had already kntmetl enough of tfie 
language that i needed sptxiflc infomialion on certain things that I 
wanted to do and didn't know how. T'hat saved a lot of money on 
beginners' lx>oks, by tlie way. I'm not sine 1 could learn C or C++ 
that way, though." 

Rocco £k)wling passes on the advice his father gave him: 

"For me, I first took an interest when I was 12 or so (wanting 


to program a game, if you cun believe it). My dad lianded me the 
SuperTalk manual and siiid something like, if you really wimi 
to learn it there's only one person whti can teach you. Yourself' 
Tliat's probably the most important thing my father ever taught me 
(you know, [resides all that hard work nonsense)/ 

Heir He continues: 

"Buy a gcxxi Ixxik in the language you want to learn. No matter 
how you actually end up learning that language, there will ALWAYS 
lx* a time wiien you need to Iracktrack and Icxik something up... a 
gtxxl reference Ixjok will lx trctisurcxi down the road." 

Patrick James has another perspective on the matrer: 

"In my case I have foLirid rliat to learn .scripting' programming of 
whatever type for me 1 have to actually lx doing .something with a 
mai objective to keep doing ir t can' just learn in the 'abstract'. My 
Ictiming will take place while 1 am actually creating .sometliing w'hich 
will lx Lisehil when it is tinished." 

Gcxxi advice: program with a puqxjse, 

[Ji Moreno recommends the ,step-by-.step approach, to start: 

"Ijearn how' to set down your thoughts in concrete algorithms, 
how' lo break things up into differem la-sks so that you can get the 
job done, 7TIEN lo pick up a new' languages it's simply a matter of 
Incoming familiar with the syntax and the advantages and 
di.sadvanlage.s of the language." 

A.S you might know, an algorithm is simply a ste|>hy-step 
prtxess to solve a problem. For example, to figure out how much 
you earn per day, you would need to - 

(1) Create a variable to represent hours (say, H) 

(2) Create another variable to represent your rate of pay 
(say, P) 

(3) Create still another variable to represent your daily rate 
(sity, I» 

(4) Multiply H by P 

(5) Display the answer, D 

Oi'courae, somew'here in diere you'll need to wrap all that math 
around an interface {or vice-vensii). 


G.D, Warner is a Technical Writer, and Iia.s been using the Mac since 1992. He's been downloading and testing software during that entire time, first 
from local BBSes, then from the internet* and toying with progranimLng (HyperCard, AppleScript* FutureBasic, OhjectBasic, C. C++, Visual Basic, and, 
of course, REALbasic). E-mail him at gdwarner@rictxhet.ner. 
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Ian OUmann posted an interesting suggestion: 

’'If you are new to programming, it might be worthwhile to take 
a c^s." 

Wliat’s so special about taking classes, you ask? Ian explains: 

'There are just too many new concepts (loops, conditionals, 
variables, etc.), which by themselves are not super difficult, but 
when combined with compiler problems, MacOS related problems, 
etc. will probably add up to become overwhelming. Compilers are 
notorious for being 'newbie-unfriendly’ and giving cryptic error 
messages. It is really helpful to have someone that you can ask 
questions. Otherwise, die experience could lie deeply frustrating.” 

Ian had another recomniendation: "At least get yourself a book 
or tw{) that teaches die language, 'fliese help organize the concepts 
in an easy-tO“leam manner Joining a computer programming club 
am be helpful as well.” 

Ian also recominends the old tried and tnie method for any 
musician to gel to Carnegie liall: 

The other thing to do i.s to pniCtice, If you are serious about it, 
devote one or two hours a day (or more) to w'riting programs and 
keep it up for a few months.” 

Steve Wilbur agrees. 

"'Fhere is no substitute for writing programs. Grab an 
introductory textbook, go to the back of the chapters, and write the 
programs asked for in die questions. Yes, they are small, menial 
programs that don't mean a thing - but that's what larger programs 
ate made of. Grab a Ixiok on the language you want to use, and 
figure it out along the way, using tlie lame programs in the back of 
the chapters in the odier Ixxik as your it k>1.'' 

An anonymous progratntiier who goes by the name 'Anon Y. 
Mous' posted these ihoughLs in supptm of die Take a Class' methcxl: 

"There's two ways to learn programming. First, ilitough formal 
educaticjn, wherein Dr. So’n’so will tell you to do this to start, leaving 
the meat of the coding ftrr homework. But when your program dies, 
dien you'll need the second way, hmte force." 

Um. .. brute force’? 

Anon explains: 'The second way is not actiatlly brute force, iLs 
mtire an exercise in cognition act nanmim . 0 ) In the second way, 
you have to exploit some understanding that you have developed 
as a mechanism for troubleshcxiting, and that's where beginners fail 
(mostly due to a lack of empirical info from the brief exposure when 
the first bugs appear)." 

Okay, formal educ^ilion, along with a healthy dcxse of trial and 
error Got it. 

John Otto, of Nisiis Software, shared his thouglUs on learning 
styles: 

"Different people learn better differcm ways. Some do better 
jumping in with modifying sample code. Some get drawn into 
MUDs, start to create dieir own, and go from there. Others need to 
sit in lecaires, ask questions, see specific diagrams in answer,” 

Jeff Massung offers more advice of a psychological nature: 

'You need to determine what kind of person you are. How do 
you learn marii? Trial and error? Reading? T^ilking to someone and 
asking questions? Or just by looking at examples? Don't try and lie 
ro yourstHf either - but once you understand how^ YOIj learn, not 


only will learning programming be easier, so w'ill everything else." 

To sum up, the comributois discussed the two different 
methods of sell-teaching and formal classes. Most suggestions 
applied well to both methods: 

(a) Type in programs from books or oilier sources 

Cb) Start witli the logic firmly in mind (or "algoritlim," to use 
the Big Word of the week) 

(c) Work with a programming club (or your local Mac User's 
Group's Programming SIG) 

(d) Determine and pay attention to your style of learning 

Taking su^estion (a), when I fifst .started playing with 
computers (the Vic-20, followed by the Commodore 64), I used to 
try typing piugnims in from magazines. 1 got to experience close up 
and personal, Anon Y. Mous' "brute force” method of programming! 

Gave up. 

Suggestion (b), starting with a good idea of the logic flciw, is 
also a g(X)d suggestion. It will certainly help to avoid bugs in your 
ctxle later, but this stage comes alter you've come up with your 
initial idea, and you're WDrking out the steps to accomplish what you 
dreamed up. 

.Suggestion (c), working with a programming club, is also an 
excellent idea... though I would recommend teaching yourself as 
much a.s you can before approaching the dub or SIG to avoid that 
feeling of helplessne.s-s a.s you listen to die more experienced 
programmers' conversal ions. 

Suggestion (d), detemiine your style of learning, is an excellent 
plan. Chances are you already know how you learn... but it can't 
hun to make sure. 

Ricki linksman (Linksrnan, 1996) has a short test you can take 
to detemiine your learning style. Once you've taken the test, you 
may discover your learning style will be one of the following: 

(D Visual 

(2) Auditory 

(3) Tactile 

(4) Kinesthetic 

As you might guess, Visual and Auditory leameis leam by 
.seeing or hearing, respectively. Tactile learners leam by touching or 
Feeling with tlieir hands, and Kinesdietic learners leam by moving 
dieir laige (ami, leg) muscle.s, dmuigh simulations, role playing, etc. 
The problem here is it’s hard to do tole-playing in computer 
programming. 

Then there's the methcxl of teaming foreign languages 
advocated in the books "Superlearning,” and "Supcrieaming 2000," 
(Ostrander^ Schrcxder, 1979, 1994, respectively). 

This method uses relaxation techniques, certain typas of 
classical music, and information read in a rtiyilimic fashion over the 
music. Alas, no one appears to have used this methcxl to teach 
tltemselves a programming language! 

1 contacted Tliomas Madden, of the Accelerated Learning 
Institute, inc. and asked about the po.ssibility of doing so. 
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"No one, to my knowledge, hits attempted to use the 
accelerated learning methodology for learning computer 
programming,'^ he said. 

"Hk- principles could easily be applied, .\ny text or course that 
exisLs can be converted to the brain-based technology. Application 
Is similar to using a computer - it Is easy if you know how. There 
would, lu)wever, need to l>e a significant paradigm shift." 

Well, that is .somewhat promising, il'not exactly concrete. I have 
contacted a few more agencies involved in this method of teadiing. 
To be sure, tliere appears to l^e some differenc'e ix^tween 
"Accelerated Learning" and "Superlearning." One of the 
Superleaming sites dcx^s niention one of tlieir customers u.sed tliese 
technic|ues to learn to program. Should tltey ever gel back to me, I 
will provide an update for you. In the meantime, if you're curious, 
see the bibliography for links and reading recommendations, 

Tlie 'take a class' method is somewhat more difficult. How 
many REALbasic cla.sses exist at your local community college? Not 
many, huh? 

Buying a book, is a little easier, finally: there are now two 
lxx)ks available on REALbasic: Matt Neubuig's "REALbasic: Tlie 
Definitive Guide," and Erick Tejkowski's "REAlJiasic For Dummies" 
are all that are available - so far 

So what to do? 

'Join us, sonny! Turn to the Dark Side/' 

Weil, here's an idea: why not stop by your local library and pick 
up a copy of a book for Visual Basic? 


Whoai Put away tliat Aane Tar and FeatherCS) kit! It's not like I 
suggested you cross over to the Dark Side (that's another column 
(I'm kidding!)); I'm only suggesting that you TAKE ADVANIAGE of 
the amazingly large number of Ixxiks out there for Visual Basic (VB 
from here on; REALbasic w'ill \y^ RB). 

Now, before you go out and start looking for VB books 
to borrow projects from, there are a few tilings you need to 
watch out for. 

VB, lieing a Microsoft product, uses Microsoft technologies ,.. 
like Active-X. Make sure you look through die project description in 
tile book youVe looking at to see tliat it doesn't rely heavily on 
Active-X or AIX) ('Active-X Data Object'). OLE is anotlier 'watch out 
For,^ but not as senous. You should be able to get away witli using 
AppleScript lor tlie OLE functionality'. 

'Ifs cheap.,, ifs sfcaacy,,, £uid it just might work." 

This method has several advantages: 

(i) You get to "program with a purpcxse/' as suggested by 
Paiiick James 

(ii) You get to use your reference books, as suggested by 
Roco Bowling 

(iii ) You get to practice, pnictice, pratice - as suggested by 
[an Olimann 
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Unfortunately, you may also get to experience Anon Y. 
Moils' "brute force" method to troubleshoot your code when it 
doesn't work. 

I chose for my experiment in this method of learning the 
book "Visual Basic Weekend Crash Course," by Rick Mansfield. 
Also at my side were the two previously mentioned REALbasic 
books, and an active internet connection. Optionally, you might 
run Virtual PC on our system, and use the demo version of Visual 
Basic to enter your code so you can see how it works on the 
Dark - um, VB side of things. 

Using tliis metliod provides one more tiling to watch f(jr when 
selecting a VB bcx)k: make sure the CD lias a functioning copy of 
Visual Basic on it. One Ixxik I picked tip recommended tlie 
Professional version “ which, of cxiurse, wasn’t on tlie CD. Of 
course, if this is all you have, it is .still useable - as long as you areJil 
planning on running Vl^ on your PC or via Virtual PC and you don't 
have a copy of the Professional edition of VTS. 

Before you start, if you have never u.sed REALbasic before, I 
strongly suggest that you go through the tutorial on REAL'S 
Tutorial page; 

http://www.realbasiLCom/download/tutorialdowriload.html 

Once you've been through that, go here: 

http://www.applelinksxom/rbu/001 

This page is the First of a series of tutorials by Marc Zeedur As 
1 type this, he is up to ^5^17, Just change that 'OT appropriately once 
you've gone dirough die first tuioriaL and go tlirougli them ;dL You 
will learn quite a bit diis way, guranieed. 

Since I liave VirtualPC on my system. I decided to create the 
project step by step - first in Visual Basie, tlien in REAlJiasie. 

The first big prciject in die Visual Basic Weekend Cmsh Course 
is a simple - if ugly — word prcxessur. 





Cheap Woni Pn)L4^or, Visual Bmk 5ri^/e 

As you might gue.ss, this project consists of a bunch ofliunons 
and an EditField, Easily replicated in REAIJiasic; 



Cheap Word Processor, REALbasic Style 


1 quickly added Balkxin lielp in RB, and tool tips in VB, 
widioLii reading the instructions in die Ixxik. I also added the End 
event to die (dose button in die VB app, and die Quit command to 
the Quit button in the RB app. At diis point, I started looking at die 
b(K)k again, and added ccxle to clear VlTs Textbox when the New 
pushbutton was pressed, and dien added similar cxxle in RB’s New 
button's Click event to detir die EdilField. 

Next, the bcxjk added ccxle to the Open pushbotton. VB was 
easy, RB took a bit more time. 

Tlie Open button should simply create a .standard Open dialog, 
and allow you to .seled a text file. 

In MA, it was simply a matter of dragging a Common Dialog 
control to the interface (you can see it there, just below the Export 
button), and typing die following code in the Open button's Click 
event: 

Private Sub ciiidOpen_Click() 

CammonDialogl .Sho’wOpen 
Textl-Text ^ Catnmonblalogl.FilsName 
End Sub 

In RB, I had to rely on my two nelenence books. Eric's liook laid 
it out for me: 

"To open a text file, follow diese four easy steps: 

1. Deiine a Ole type for text files, 

REALbasic may have already created one for you, but check 
anyway by selecting File -> File Types." 

This gave me pause for a hit, beaiuse File Types wasn't under 
File anymiire; it had lieen moved to the Edit menu. 

"2. Create a Texllnput object in your code as follows; 
Dim Textin as TextInputStream 

3, Send a Folderltem the OpenAsTextFile message as 
follows; 

f.OpenAsTextFile 

4, Read each line of the text file until you reach the end 
as follows: 
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Text In = f^ReadLine" 


After all of that, 1 ended up with this code for my Opea 
pushbutton: 

Dim TextIn ss TextInputStream 
Dim F as Folderlten 
DIM myText As Strings 

f=GetOpeiiFol dec Item ("TEXT”) 

//Nuce tlie caps tn TEXT. Usipg lowercase letters results in code wlikh, wben nm, 

//tbes not show any test files m the diaJpg lx>s. 

If fOnil Than 

TextIn == f.OpenAsTextFile 
While NotfTextln.EOF) 
myText ” Textin. ReadLlne 

EditFieldl.Text - Edltfleldl.Text + ntyText+thr(13) 

Wend 
End If 

It worked as advertised (after i fixed that 'text' blunder 1 
mentioned in the commenLs), but that was a lot of work - at least 
when compared to VBVs method. 

Next die projea called for coding? die Save pushbutton. This 
was pretty easy in bodi RB and VB. 

Next we did the code for the Print pushbutton. Here we see 
the differences in tlie Windows approach and the MacHnUxsh 
approach to things. 

Tlie code for the Print button in VB is pretty straigfitforward: 

Private Sub nmdPrint_Cllck{) 

If Textl.Text <> Then 

Printer.Print Text 1 .Text 

Printer.EndDoc 

End If 

End Sub 


Tlie code for RB Ls more Involved. Once again I turned to Hric's 
"REAliiasic For Dummies" lxK>k ... and found a whole chapter just 
devoted to printing (chapter 13). 

Before 1 could whte die cxxle for the Print pushbutton (which, 
later in tills projea, wilJ Ix^ removed anyway), the Print and die Page 


Setup.., menu items will need to be enabled, the appropriate menu 
liandlers aeated and the code written .,. and cxxle to create and 
save the Printer Setup options in a Preferences file, and load the 
Preferences when the application opens ... tlien the code For the 
Print button can finally be written (tliough 'oopied-and-pasted' Ls 
somewhat more accurate). 

After I entered die VB Print button code, I tested it. I didn't get 
a dialog box ... but my desktop printer (set to "Print to File") spat 
out an untitlcxi PosiScript™ file, so it worked. 

I'm still working on finishing this program (out of time due to 
a short-fuse deadline) liut 1 highly recommend doing diis exercise. 
If pnjgramming widi no real purpose doesn't work for you, diis 
method will do the trick. It forces you to look up die Mac version 
of the ccxle that your VB brxik lias in it. Sometimes this can be a bit 
of a chore ... hut it's well wordi die effort. 

Finally, Phillip Stripling had one more important piece of 
advice: 

"Have fun, Glen." 

1 suggest you do the .same. 
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MAC OS X 


by Andrew Stone 


Writing Plug-Ins for Cocoa: 

iPhoto to PhotoToWeb Exporter Plug-In 


Alter youVe been wmking with Cocoa for a while, you’ll 
come to appreciate the truth behind this statement: If it’s hard to 
do, then you’re not doing it right". By this 1 mean any coding 
solution that involves convoluted logic, going beneath the API or 
using undocumented methods, is probably not the right approach. 

However, sometimes delving into secret API is the faste,st 
way to get something done. Caveat Hmpron your program may 
break if the underlying methods change! I’hat’s why 1 usually 
admonish against using private, hidden methods. 

This anicle will explain how to peek inttj the guts of an 
Objective C Cocoa application. iPhoto, and WTiie a Plugin that 
allow's users to export their photos to the Stone Studio digital 
photography to web application ]dir>toToWcl)®. iPhoto tjffers 
only limited web production facilities, whereas PhotoToWeb 
otTers a complete suite of vvel> design functionaljiy, including the 
ability to create linked multi-level photo websites. 

My design objectives were to keep the Plugin .small and 
very simple, including using the existing PhotuToWeh 
AppleScript APT This way, there are no laide or file format 
dependencies in the Plugin. In.stead, we simply build a script 
that asks PlujtoToWeb to build a new album with the exported 
photos. Also, instead of duplicating the user’s pliotos, we just 
export the full path names since PhotoToWel> can build albums 
out of any images anywhere on the used.s disk or network. 



Figure li iPhiyto hadii !be PbotaToWeb exiH^ri Plugin via 
Share - lixport 


Ciass-Ddmp Is Youk Friend 

IF you want to see the inner architecture of an Objective 
C application, you’ll need class-dump, which you can 
dowmload from: 

http://www.om nigroup. com/--nygard/Projects/index.html 

class-dump is a laility for examining the Objective-C 
segment of Mach-0 files. It generates the ©interface and 
©protocol declarations for classes, categories and protocols. 

Class-dump is open source, and has been an ongoing 
project since the early NeXd’ (the grandfather of OS X) days. It 
has had several contrthiitors, including Eric P. Scott, Steve 
Nygard, James Mcllrce, Tom Hageman, and Carl Lindberg. IPs a 
Unix executable and has no GUI. Running it without arguments 
gives you the options: 


Andrtfw Stone <andrew©stone com> is founder of Stone Design Corp <htt[-)://ww'w.stofiex'om/>, autkir of Sttmu .Studio^"^ and Create®, and divides 
his lime between farming on the earth and in cyperspace. 
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class-dump 2.1,5 

Usage: class-dump [-a] (AJ [-e] [-R] [-C regex] [-r] [-s] 

[-Sj executable-file 

a sbo¥ instance variable offsets 
-A show implementation addresses 

-e expand structure (and union) definition whenever 

possible 

-R recursively expand @protoc£>l <> 

-C only display classes matching regular expression 
•r recursively expand fratiieworks and fixed VM 
shared libraries 

-s convert STR to char * 

'S sort protocols* classes* and methods 


You CRn dump all the dasse.s of an application, or just tlicjse 
matching some pattern. Since we're in!ere.sted in the Export 
niethcxis, we ll run it like this; 

class-dump -G Export 

/Appllcatione/iPhoto.app/Conrents/MacOSX/iPhoto 


which outputs; 

(^protocol ExpottIraageProtocol 
' directoryPflthr 

- (void)cane:elExportBeforeEeginning; 

- tvoid}cancelExport: 

- (voidistartExport; 

- (void)clickExport: 

■ (void)disableControls: 

- (void)enableControls: 

- window: 

■ getlmageDlctioriaryAtlndex: (unsigned itit) fpl6: 

• getTbumbPathAtlndex:(unsigned tnt}fpl6: 

- getImagePathAtlndex: (unsigned liit)fpl6; 

■ [char) litiagelsPortraitAtlndex: (unsigned int)fpl6r 

■ imageSelectlonArray: 

- (imsigned int) image Count; 

@cnd 

©interface ExportMgr:NSObject <ExportImageProtocol> 

ArchiveDpcument *inDacmiient: 

KSMuxableAtray *inExporters; 

KeyHgr •mSelection: 

ExportController •mRxpartController: 


+ exportMgr; 

- (void]releasePlugins: 

- (void 3 BetExportControl1e r:fp12: 

- exportControllar: 

- (vold)setDocumentrfpl2; 

- document; 

- (void)updateDocumentSelection; 

- (unsigned Int)count; 

- recAtlndex:(unsigned lnt)fpl2: 

- (void)EcanForExporters: 

■ (unsigned intjimgeCoant; 

- iniageSelectionArray: 

- (charJlmageTaPortraitAtlndexI(unsigned int)fpl2; 

- getlmagePathAtlndex:(unsigned int)fpl2: 

- geLDsumbPathAtlndex;(unsigned lnt)fpl2i 

- getlmageDlctionaryAtlndex:(unsigned int3fpl2; 

- getlraageRecAtlndex:(unsigned int)fpl2; 

- (VDid)enableControls; 

‘ (void)dlsableControis; 

' window: 

- [void)elickExport; 

- (void)startExport; 

■ (void)cancelExport: 

- (void)cancelExportBeforeBeginning; 

- directoryPath; 

‘ (voidj_copy$election:fpl2: 

©end 
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methods defined in the Export! mageProtocol, add a few keys 
to the Info.plisi file, and provide an interface file with any 
special controls. You can open some of the existing Plugins 
inside iPhoio by control-clicking iPhoto in Finder, looking 
Inside the Contents/Plugins folder, and controFclieking one of 
the Exporter bundles. 

Of course, without documentation or source, we’ll have to 
guess at what certain methods do. ExportMgr has a class method 
'‘+exportMgf’ w’^hich provides us with the ExportMgr instance, 
Reading over the ExportMgr class methods, we see methods for 
retrieving a set of photos one at a time, and getting information 
ab{)ut that photo. 


Making Plnglns 

To make a loadable bundle (which is exactly what a Plugin 
is), launch Project Builder and choose New Project..,, select 
"Bundle'', provide a path, and save. Create a new empty nib in 
InterfaceBuilder, add a CusiomView (we really don't need a 
windt>w, just a view' containing our interface elements), and save 
it into your bundle project. 

We only need one class, “PholoToWebExport”, l>ut we also 
need to include the protocol as defined in ExportPluginl^rotocol, 
and declare that our objea conforms to this pnitocol: 

r PhfJti>ToWchliJtpfjit.h 7 

(flmpgrt <Coc.oa /Cocoa, h> 

©protocol ExportPluglnProtocol 

- (void)cancelExport: 

- (void)uiilockProgreefi; 

- (void)lockProgress: 

‘ {void *)progress: 

• ( void)perforn[Export; fpt&: 

- (void)startExport:fpl6: 
defaoltDirectory; 

• defauItFileHaniE: 
requlredFlleType: 

' (void)vievWillBeDeactivatefi; 

(VO id) viei/WlilBeAc ti va ted ; 

- laatView; 

- flrstView; 

• settingsView: 

- inirWlthExportlmageObj:fpl6: 

@etid 


#definc TS„NULL(s) (Is || [s iflEqtialToString:© '’*]) 

(/define NOT_NIJLL(sJ {s IL 1 [s isEqualToString:©""]) 

©interface PhotoToWebExport : USObject <ExportPluginProtocol> 

t 

TBOntlet id settlngsVlev; 

TBOtitlet id titleFxeld: 
tBOutlet id iinageView: 

IBOutlet id actlonMatrix: 

IBOutlet id finishView; 

IBOutlet id firstVlew: 

Id exportMansger: 

Component Instance lEy Comp orient: 

NSString ‘_lastDirectO£yPathr 

f 

■ (void)doTtfuloadLatest:(id)sender; 

©end 

Ibmpoft "'PhotoToWpbKvpnrt .h" 

#import <Carbon/Carbon.h> 


©imp1emeD tation Pho t oToWeb Exp o r t 
// initialbEcr 

// we'lJ gpb the ExportMgr mstrmce - although you could 

// just use the class method + [ExportMgr exportMgr] 

- initWithExportlmageObj:fpl6 [ 

self = [super ifiitl ; 
exportManager = fpl6; 

// wt'U use AppleScript to talk to P1i<itoToWcb: 

myComponent = OpenDefaultComponent(kOSAComponentType, 
kO SAGe ner i cS c ri pt ingC ompo netit S ubtype): 
return self: 

1 

// if there are photos to export, create and mn an AppleScript 
// to load the phonw into a new l*homToWeb album: 

- (vDid)doExporttfplb I 

BOOL good = YES; 

if ([exportManager imageCount] > 0) 

[self cuuScriptI[self scriptCommand]]: 
else I 

NSRunAlertPanel(©"No images selected",@"No images to 
export".OK". nil. nil); 
good ” NO; 

} 

// make panel disappear ^ miglu be <Kher way: 

[[exportMansger exportGontroXler] canceliself]; 

// jlrinp tbf album to the front so um.t can make web site or thumbnails etc... 
if (good) [iNSWorkspace sbsredWorkspace] 
openFile:[exportManager directoryPathl 
wlthAppllcatlciii:©"PhDtoToWeb"] ; 

I 

// this Ls the guts of the plugin 

//Well create the AppleScript script necessary to export 

// the selected photos, and attempt to grab as much informatioti 

// as the users have provided in tPhoto - such as comments, rotation 

//m>p information, title, etc. 

- (NSString •JscriptConnnand I 

NSHutableString “e iNSHutablaString 
strlngWithGapacity:2000]; 

unsigned i, c = [exportManager imageCotint]: 

// for next time the user runs it, we'll have their preferred directory: 
[_lastDirectoryPath release]: 

JastDirectoryFath = [[l^xportManager directoryPath] 
BtringByDeletlngLaBtPathCotnponent] copyWithEone:[aelf zone]]; 

[s appEndatring:@"telI application V^PhotoToWobV"Vr"]t 
Is appendString;@‘'\t3!iake new album at before front 
albuni\r"] : 

[a appendString;@"\Ttell the front album\r"I; 

// this will prcvem the ApplcSeript fn>m liming out if there is a huge number of phtHtJs: 
[s apperidString:@"\tUignorlng application responses\r"] : 

for (i = 0: i < c: i++) I 

NSString ^path “ [exporiHatiager 
getImagePathAtIndex:il: 

NSDictionary ‘diet = lexpartManager 
getTinageOlctlonaryAtlndex: l]: 

Int rotation ^ [Idict objectForKey:@"RDtation''] 
intValue]; 

NSStrlng 'title = Idlct objectForKey:©"Caption"]; 
NSString 'story = (diet objectForKey:©"Annotation"]; 
// could be nil 

NSDate “archiveHate " [diet 
objectForKey:ArchiveDate" ] ; 

NSStrlng 'date = [[NSCalendarDate 
dateWlthTinLelntervalSinceReferenceDate: 

[archlveDate timelntervalSinceRsferenceDate]] 
descrlptlonWitbCalendarFomtat:©"Archived: %e %Y"]; 

[e appendStrlngt[NSString 

strlngWlthFormat;©"\t\t\tadd photos in path]]: 
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it Crotation != D) t 

ts appendStriog:[NSString 

strineVithTorntat:@"\t\t\tser the photorotation of laet photo 
to lidU^H rotation]] ; 
i 

if (NOT^NOLLttitle)) 

[s appendString:[NSString 

strlngWithFormat:@'‘\t\t\tset the title Of last photo to 
VWV\r'\ title]]: 

if (N0T_NULLfstory}) [ 

[a appendStrilig; [NSString 

atringWithFornjat:@"\t\t\tset the text contents of last photo 
to N0T„NULLCdate)7 [NSString stringWithForrnat: 

XS'* * story, date]; story] ]: 

I else if {NOT_KtJLL(date)) 

[s appendString:[NSStrlng 

stcingWithForiii3t:@"\t\t\tset the text contents of last photo 
to date]]; 

I 

[a appendstringVt\tend ignoring\r"]; 

(s appendString:[NSString stringWlthFormst:@”\t\taave in 
[exportManager directoryPathJ ]]:; 

[a appendString:tend tell\r‘*] ; 

[s appendString:®'*end tell\r"] ; 

return s; 

1 


• (voidjperforniExport :fpl6 I 
// not sure how this (Mers fn)m stanExpon hut doesn't acorn to be nmJed 


(void]startExport:fpl6 E 
[self doExport:fpl6]: 


// if the plugin has been run before, use tile last savcici pjiih 
// Otherwise chtMisc a standard locatit m: 

’ (id) defaultDlrectory [ 

if (NOT_NULL(_lastDlrectoryFath)) return 
^iastOirectoryPath; 

return [HSHomeDirectory() 
stringByAppendlngPathComponent: @’’Docunients*'); 
I 


// here's a nice w to guarJniec uniqueness of the album name 
// concatenate the year-month daj-seconds: 

- defaultFileNartie I 

return [NSString sttingWithForniat 
%d’\ [[NSCalendarDate calendarDate] 
descriptionWlthCalendarFormat:@"%y‘%ro‘%d"J. [NSDate 
timelntervalSinceReferEnceDate]]; 


// this is PhotoToWeb's single Album file type: 

- tequiredFileType I 

return ©"album"; 

1 

- lastView I 

return ftnishView; 

1 

‘ firstView i 

return flrstViev: 

I 

- settingsViev f 

return settingsView: 

I 


//An action mcthtHl to preivide user with latest version of PhotoToWeb: 

• (void)dovnloadLatest:(id)sender [ 

[ [NSWorkspace aharedWorkspace) openQRL;[MSURL 


hRLyith£tring:@"http: //ww, stone, con/NewDownlDad .htmltfPHOTO"] 

1 : 

1 

// T can't think of anything to do in these two metliods 
// In a more complex plugin^ you might set default values: 

- (void)vievVillBeDeactivated [ 

) 

- (void)viewWillBeActivated [ 

I 


// these next 4 metJiods are not yet flushed out because 1 haven't figured 
// out exactly what to do with them - if ytiu do, email mel 

- (void)eanceiExport E 
1 

- (void)unlockProgross I 

I 

- {void)lockProgtass ! 

I 

- (void *)progroes I 

return NULL: //7? 

1 

//ThcAppleStilpi compilation methods: 

^define CHECK 

//lprinif(stderr.’'resu]t cixle = %d’*.ok); 

//This converts iuiAEDcsc into a corrcspontling NSVhhie, 
static id aedesc_tD_id(AEUesc *desc) 
t 

OSErr ok: 

if (desc->descriptorType = typeChar) 

NSMutableUata ‘outBytes; 

NSString *txt: 

outBytes = [[NSMutableUata alloc] 
initWithLength:AEGetDescDataSize(dose)]; 

ok = AEGetDescData(desc* [outBytes rautableBytes], 
[outBytes length]); 

CHECK: 

txt “ [[NSString alloc] InitWithUata:outByte43 
encoding:[NSString defaultCSiringEncoding]]: 

[outBytes release]| 

[txt autorelease]; 

return txt: 

I 

if Cdesc->descripTOrType “ typeSIntl6) 

I 

Sint16 bufr 

AEGetUescBata(desc, 6buf. sizeof(buf)): 
return [NSNumber tnunberWithShort:buf]; 

1 

return [NSString etringWlthFormat:©"[unconverted AECesc, 
type=\"14c^c^c%c\"]" * ((char * )&{deRe->dest:riptDrType)) [0] * 
((char ’ )&(deaC‘>deai!rtptorType)) [1] t {(char M&(desc- 
>descrlptcirTypB)) [2], ((char *)fii(desc->descriptorType)} [3] ]; 

1 

- Cvoid)runScript:(NSString *)txt 
I 

NSData *scriptChars ^ (txt dataUsingEncoding:[NSString 
defaultCStringEncodingJ 1 : 

AEDesc source, resultText: 

OSAlb ecriptid, resultld; 
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OSErr ok; 

// Convert the source string into anAEDesc of string type. 

ok — AECreateDesc(lypeChar» [scriptChars bytes]» 
[scriptChars Length], ^source); 

CHECK; 

// Compile the source into i script, 
scriptld ^ kOSANullScriptr 

ok OSACoinplle(n]yComponent, Scsource, kOSAModeKull. 
Siscriptld]: 

AEDisposeDesc(^source); 

CHECK: 

// Execute the seripi, using dciaults for everything, 
resultld = 0: 

ok = OSAExecuteCmyComponent. scriptld^ kOSANullScript* 
kOSAModeNuIl, &resultld): 

CHECK; 

if (ok == errOSAScriptError) I 
AEDesc emuffi* erstr: 
id ernumobjH erstrobj: 

// Extract the error number and error message from our scripting component, 
ok = OSAScriptError (myComponent * kOSAEc rorNumbei:. 
typeShortlnteger, ^ernum); 

CHECK: 

ok ^ OSAScrlptErTorftnyComponent, kOSAErrorMessago, 
typeChar* Serstr]; 

CHECK; 

// (k>nvert them to ObjC types. 

ernumobj = 0 edesc_to_ldC&ernmn): 

AKDigpoaeDesc{&etuu!ii) : 
erstrobj ^ aedesc_to_id(Sterstr); 

AEDisposeUescC&erstr): 

txt ^ [KSString strlngWithForntat :@**Erroi:* number^lC^* 
cnessage=%@" . ernumob j , erstrobj I: 

I else I 

// If no erran extract the result^ and convert it to a string for display 

if (resuitid !" 0) [ // apple dt>esnt mention tliat this can lx- d? 
ok * OSAhisplaytiayCoiiiponent. resuitid* typeChar* 
kOSAModeNull. ^tesultText): 

CHECK; 

txt = aedefic_to_id(&resultText ); 
AEDisposeDescC&rosultText): 

) else ( 

txt ^ @”tno value returned]’’: 

I 

OSADispose(rayGomponent. resultId): 

1 

ok = OSADispose(myComponent* scriptld)s 
CHECK: 


@end 

After you compile your Plugin, tlrtjp lx inio the Plugins 
folder in iPhoto^ relaunch iPhott), choose ‘’Share" and ‘’Expt^ri", 
and if all is well, you1l see your Plugin as a lab in die Export 
TabView window. 

Then Appij; Released iPHtxro 1.1 

Before diis article went to print* Apple released an update 
to iPhoto—and indeed, my Exporter bundle broke! First* I 
looked through the console error messages and saw that my 
Plugin wasn't responding lo certain messages. Then* 1 used 
class-dump to confinn that some protocols had changed. 

The first problem svas that my Plugin’s main serringsView 


didn't respond to the ExportPluginBoxProtocol protocol: 

ip r otaea1 Expo rtPluginE oxP ro t oc o1 

- (char)performKeyEquivalent:fpl6: 

@end 

So, by looking at the nib files in the Apple-provided 
Plugins* 1 deduced this simple NSBox subclass: 

iinterface P2WExportPlugiiiBox:tiSBax (ExportPluginBoxProtocol) 

I 

id raPlugin: 

1 

iend 

@impleinentation FZWExportPluginBox 
• (char)perfonnKeyEquivalent;fpl2 \ 

t 

i&end 

Drop diis source file into the Interface Builder class window 
to have it read the file. Assign the clas,s “P2WExportPluginBox" 
to the NSBox containing your Plugin controls in Interface 
Builder. Connect the "mPlugin" instance variable to the file's 
owner. Save, build, and drcjp into the Plugins folder, (An 
intere.sting sidenuie: variable names can reveal a lot. The coder 
here was probably an old Mac toolbox programmer, as indicated 
by the k)wer-case as in ’‘my", for tlie ivar. Objective-C 
ccxlers conventionally use an underscore to prefix ivars, so the 
ivar name would have been “_plugin".3 

Second, a few more methods were needed in tlie main 
Plugin class to gel it to work again; 

@imp1ementa tion P bo toToWehExpo rl 

- (NSString ')narae 1 

return i&^Stone Design’s iPhoto to PhotoToWeb Exporter”; 

[ 

- (BOOL)treatSingleSelectioiiDifferently i return NO; ] 


OjNcwmm 

Cocoa, especially the Objeaive C flavor, is the future of Mac 
OS X, as evidenced by the new apps coming out of Apple 
wrinen almost eniirely in Cocoa, Dynamic runtime loading 
comes free* and you can examine ihe classes and methods in an 
application using class-dump. Knowledge of Carbon is still very 
useful. For example* in tills Plugin w'e use it to compile and 
execute our AppleScript. It's a good idea to keep an agnostic 
attitude towards the various Apple API’s* 

Using the techniques outlined in this article* you should be 
able lij add all sorts of functionality to the ever-increasing 
numl)er of applications available for .Mac OS X, 
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KOOLTOOLS 


By Micbm/ Hawey 


ChronoSync 

ChronoSync is a file synchronization utility that lets the user 
backup, save, and synchronize files to local or network locations, 
and schedule these fimctions to run at specified times. Bet you 
couldn’t figure tliat out ftom reading the name. 

ClironoSync’s documentation is provided througli tlie Help 
Center. It is complete, and easy to use. The manual c^an lx: read 
through, beginning to end, to leam all the details of the program, 
or searched to find specific information. Additionally, ChronaSyne 
makes use of TcxM Tips throughout the application to make 
identifying various bunoas and elements of the program easier. 

Synchronization settings are established in documents, which 
are the main windows of the program. On launch, you will be 
presented with a new, untitled, dcx'unient. In preferences Ls the 
option to disable tills feiiture. The main window presents you with 
a ttx>lbar displaying buttons that activate die main fimctions of the 
program, and tliree tabs. Hanging off the riglit side of the window 
is a drawer called the Options Drawer. Additional setup options are 
listed here wliich are sjxxific to each tab. Tliis can l>e opened or 
closed from the Actions menu. 
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ihe first tab is Target. The Target tab Is when" you set the local 
and rejnote folders you want synchronized. Ihe options draw'er 
here lets you set die synchronizing direction, and tlie kind of file 
system on the taiget and remote disks. 

ClironoSync also supports drag and drop set up of taiget 
folders. From ilie Finder, just drag a laiget disk onto die dexument 
window, and drop it tliere. Hie upplicaiion will tlien display die 
path <jf the folder you jusi dropped on to it. In fact, dragging works 
diroughout the program. Widiin tlie Rules tab, for example, 
dragging a file onto die window will have ids attributes copied into 
whatever fields are selecied at diat moment, much like dragging a 
file onto die search window of Sherkx:k does. 


Once taigets are established, you are then able to determine 
rules to apply to your synclironizations. Out of the gate, the .simple 
rules are easily configured, and will be more dian enough for most 
users. Intermediate rules settings dlow for very fine defmition.s for 
what to include in a syndironizadon. Advanced .settings allow the 
same spec'ific control over inclusion, just like the intermediate 
settings, but also allow die user to set exclusion criteria, as well. 
The Option Drawer fur dds tab holds die radio bunons to change 
between basic, intermediate, and advanced mles displays. 

The third tab in the dexurnent is Analyze. From here, you can 
compare files at die local and remote locations, see their 
synchronization status, and wliat Ls excluded. You can also set 
exdusifjuis. Highlighting an item and clicking on the Exclude 
button will pul an X between ihe ItKal and remote files, indicating 
it will passed over during all subsetjuent synchrunizatioas. The 
options drawer for Analyze displays the syndironizadon direcdon, 
the same as is displayed under the Target tab. The rest of the 
dniwer is given over to Special Handling choices. One of the more 
significant choices is verl-xxse logging. This one is, by default, 
unchecked, but should be, as the basic logging does not list specific 
errors w hen diey crop up during scheduled mns. 

Once all your settings are e.stablished, you are ready to 
synchronize your files. You can do this manually, simply by 
clicking on the Synchronize button in the document, or by 
scheduling it. From the Actions menu select Add to Schedule. 
The presented dialog lets you schedule when ChronoSync will 
run the document with great detail You can also choose to run 
the schedule at application launch or quit. The last item in the 
Actions menu will be either Resume of Suspend Scheduler, 
which oddly enough, starts or stops scheduled doc li merits from 
running. Show Scheduler from the View^ menu wnll display a list 
of all the scheduled documents. 

Running schedules over the network is simple. Tile first time 
a schedule mas, and the netw'ork volume is not aviiilable, you will 
Ix^ given the option to allow ChrontxSync to access log in 
information from the Keychain. You can allow access once only, or 
alw^ays. If always Ls selected, die volume wall automatic:ally be 
mounted on all suh.seqiient runs of the sdicxlulcxJ document. 

ChronoSync falls short in only one area. It does not run as a 
daemon or facele.s.s background application. If the program were to 
run scheduled tasks in the background, prtwiding only enough 
infontiation on .screen to let the user know' it's wxirking, it would 
lx far more ideiil. 

This is a fairly minor cjuihble, though, and overall tlie 
program is very capable. It lacks a few of the bells and whistles 
of some of its competitors, but that is to it's advantage. 
ChronoSync is a small, focused application that does it’s pb well. 
And, at $19.95, it is much less expen.sive than some of tlicjse 
competitors, ChronoSync Mac OS X only .shareware available 
direedy from Econ Tedinologies, Inc.. 

• http://www.econtechnologies.corn/ 
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Your Data Isn’t 
an Important Part 

of the Job 

— It IS the Job. 


VXA FireWire 


"/ can stick 
my entire 
hard drive 
onto a tape 
7 times 
— that^s Just 
plain cool!** 




For Apple Users 


Odier backup media, such as CD-RWs and DVD-RAMs, 
simply can't compare to VXA-1 tape technology when it 
comes to capacity, transfer rate and overall price. 

Fast, economical and easy-to-use. 

VXA FireWire offers: 


The High-Performance 
Tape Storage Solution 


Ultimate File Security 

• 100% Data Restore and Interchange 

• Plug-and-Play Connectivity 

Sharcible Media 

• Multi-Gigabyte File Transport 

• Portable, Hot-Pluggable 


Technology 


^^VXAT^e 

hnadonTr^an 


DVD RAM 
CD RW 


Zip 


Capacity 

in MBs 


13000 

lOOOQ 

9400 

700 

250 


Transfer Rate Price 
in MB/sec per MB 


3 

$0.01 

1 

$0.05 

2.7 

$0.05 

1.9 

$0.50 

1.2 

$0,76 


Real Time DigitatVideo 

Cross-Platform Compatibility 

• FireWire/IEEE 1394/ilJnk Supported By 
All Major Manufecturers 


Call Exabyte sales at 1-800-774-7172 
or visit us on the web at www.exabyte.com 

Tape Storage By 

-VXA- ^Exabyte* 


© Co^jyrigfit Z002 Corporation , Ai( rights reserved. VXA andVXAtape are rostered trademarks of Exabyte Corporation, 









PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westford, MA 


One Time Pad 

A one-time pad, used pnoperly, provides a simple and 
unbreakable method of encryption. The ""pad” Is a nmdom bl<:x;k of 
data equal in length to the message to lie encoded. Two copies of 
the pad are needed one for the message sender and one for the 
message receiver The message to be encrypted is combined witli 
tlie data in tlie pad by, for example, an exclusive OR; transmitted to 
the recipient, tmd decoded by tlie inverse operation. To lie 
Linl’)reiikable, the pad must consist of truly randt^m data, and it mast 
\yc used only once. 

Of course, you still need to securely exchange a one-time pad 
for each message to be encrypted. Let's imagine iJiat tills is K>o much 
trouble, so what we are going to do instead Ls to use some cotnmon 
text as tile Ixisis for our one-tune pad. We ll selea tlie “random” 
bkxk as an tjfFset from the first character in tliat text. And we’ll reuse 
our "'one tiine” over and over again for different messages, wiili 
differcMit offsets. Since tile text isn’t random, and tlie one-time i>ad is 
used multiple times, we may ktve compromised security somewhat. 
Thus Ls a Good Thing, hecaLLse your (’.hallenge is to crack a set|uence 
of messages encrypted with this .scheme. 

The prototype for the ctxle you sliould wmte is: 

void InltOneTimeFad ( 
const char ^oneTimsPad, 

/* NUIX ti-TitUnatL-d toa lo Ix' lutd for the tine-lime pud 7 

/*Yoii ifhouJd ignore (skij>)aiiy diiinKtm m»t in ilii; mngc t)x2tWk7E,indiJ!!iiw V 

const char ‘dictionary[J, 

r lisi of NlUX.^tminatrd wonk in ihr itiASdl imJer */ 

long numDlctlonaryWords 

char ‘DecryptMessage( 
r return deoypied message 7 
const char ‘encryptedHessage. 
r NliU terminated text it> dea>de 7 

/* < iuamnreed to contain only chantetm in the range (lx2fHhi,7E, incIiMvc 7 
long ‘offset 

/* oltsci into die oncrimel\id liiat vm tkterminc to be tlx* ha.MS for entrypEion */ 

3; 

voi d TemaOneTimeP ad Cvoi d}: 

Your IniiOneTimePad routine will Ix" calleti each time our 
Imelligence Service aiprures a new one-lime pad being used by our 
adversiity. You will also lx given a .sortetl diaionaiy' of words in the 
vtx'ahiilary of our adversary. You am alkote memory and do 
whatever aruilysLs might lx appropriate. 

For each intercepted message, ycjur DecryptMessage routine 
will lx called widi tlie encrypted text. Fortunately, we know that 
our encrypting adversary^ uses tlie oneTimePad in a consistent 
manner. S/he u.ses a section of the pad starting at an offset known 
to the sender and receiver, but unkmiwn to us. Tlie section of tlie 
pad used is as king as the encrypted message, ignoring any 
cliaracters in the pad (Ixyond die offset) outside tlie range t)f 
printable ASCU characters C0x20-!}x7E}, Tlie n*^ character x of die 
clear text is encrypted as x+y-()x20, modulo die legal range of die 
diaraaer set, w here y is the n^^ legal character of the oneTimePad 


beyond die offset value. So, if the oneTimePad [offset] starts with 
“When in die Course<CR> of human events”, and your clear text Ls 
“The British are coming.”, the encry'pted text would be 
",QKnB\XtA\N<SP>^Kab[rWUmYUgv”, where <CR> denotes a 
nonprintable (and ignored) carriage rerum and <SP> denotes a 
space characier that you might not otherwise notice* Note that 
nonprintable characters are counted in deiemiining the starling 
position (offset) within the pad* 

You .should detenuine die section of die one-time pad dial was 
used for encryption, decrypt die inessiige, store die oneTimePad 
offset used lor diis messiige, and return a NULL-terminated string 
containing the clear text. 

Your TemiOneTimePad routine should return any dynamic'iilly 
allocated memory. 

Tlie winner of this Challenge will lx the entry that correctly 
solves all test cases while incuring the lowest cast. Solutions will 
incur a cxxst of 10 points per millisecond of exeaiiion time, including 
the time inairred for initialization, decTyption, and temiinaiian. You 
aan earn a Ixiiius of up tt) 25% reductifin of incurred cast based on 
a suhjeciive evaluation of the ciaiity of your ctKle and commentary. 

Iliis will lx a native PowerPC Qtriion Challenge, using the 
Memiwerks QxieWarrior Pr) 7.0 development environment, Plea,se 
lx certain dial your code is airixnlzed, as I may evaluate tliis 
Challenge using Mac OS X. 

Winner of the February, 2002 Qiallenge 

In Felimary, we xsked contestaiiLs to delragment a simulated 
disk drive. Sc<3ring was based on making tlie fewest numixr of block 
OKives, regardless of fikxk size. We also awarded a Ixiiius of 25% for 
incoqiorating optional features, like an untimexi display of 
defragmentation pnigmss, and anodier 25% Ixmiis based on 
elegance of the solution. Congratulations to Jomiy Taylor Ibr taking 
first place in die Disk Defragmentation Challenge. 

Six people entered srilutions for diis Cliallenge and five of tiiase 
solved the problem c'oirectly, (The sLxdi vioLiied die constraint 
ag;iins1 overlapping the source and destination bkxks.) 'File Ixst 
sairing solution, by Jan SchtiLsmun, was submitted lifter the deadline 
and wa.s therefore not eligible to win. Tliree entries, including tali 
kainy's and the sec:ond-plac:e enliy from Ernst Munter, provided 
(iptifins TO display die evolving .solution or to replay die solution, 
jonny also provided menu optioas to contnil tlie speed of die 
display. Jonny’s entry required approximately 25% fewer moves to 
defragment die disks, although it recjuired nearly diree times as much 
compuuition time to do so* 

Several of die entries chose to defragment the simulated liles in 
ways diat also consolidated all free space into one bkxk. Tliis 
Ixfiavior was not requimd, and Jonny chose not to do that. Instead, 
he chose? to leitve large fragments in place wheie possible, reasoning 
diat diese are less likely to lx reloc^ded on densely occupied disks 
widiout Ixing .split up into multiple pieces. Jonny first employs an 
“intelligent move” algoridim, described in the 
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ConsiderMcwingFraginent rnutine, that selects and moves Hie 
fnignienis which, when moved, would allow oilier fragments to lie 
moved to their final deslmation. For fragments that remain after 
applying ilie intelligent algorithm, the GuaranteedMoveFtagtnent 
routine moves all remaining file fragments to their final destination, 

I evaluated soluiiorLS rising five test cases, one small and 
rt.‘laiively simple, and tlie others siniulaiing densely populated disks 
witli varying levels of fragmentation. llie subjective evaluation of 
features was lyased on whether a display option wtts present, and 
on otlier menu optioas provided to contral die solution and the 
display. The "elegance" criterion w'as based on code commenuiry', 
coding style, elevemess of the algoritlim, and on die conciseness of 
die Cfxle. Johnny’s winning entiy^ was downrated a litde liecause of 
tile complexity of the cxxle, but earned points for Ixfing well 
cximmented. As it turns out, entries were ranked in die saline order 
both with and without eonsidering die subjective criteria. 

Tlie table below lists, for each of the solutioas submitted, the 
toed number of disk blcK'k moves used to defragment the desks, die 
toed execution time in microseconds, the raw' score based on moves 
and execution time, die subjective Ixinuses basexi on eleggnc^* and 
features, and the total mire after taking the licjnuses into 
consideradon. It alsci lists the programming language used for each 
entry and the operating system used for the entry. As usual, the 
number in parentheses after the entrant's name is the total number 
of Challenge points earned in all Challenges prior to dds one. 


Njunc 


Tlnic 

1 

1 

Total 

Ud^ 

OS 




Score 


(on.o) 

Score 



Jfinciy Taylwr (37) 

59=^1 

\iW^ 

786190 

0,65 

roo 

461886 

c+-^ 

CLissic,/9 

Klrnst (Z7S) 

im 



1,00 

0.75 

470502 

C++ 


IjuttfJvit N'Kinlle 


279473 


0.75 

0,00 

1267352 CyOlifC 

£2)i:ri4vX 

Allen Sttinger (49) 

7733 


imm 

1,00 

0.00 

1717775 


C4j1xhi^'X 

Jyn SchcH'iiTOin £ Ui> < tule) i224 

\(m)7 

738S81 

0.75 

0.90 

U3916 

c 

Claiisk79 

T,S. 

49.39 

126949 

109.3346 

0,65 

000 

91567^ 

C++ 

TcrnrEtniiL'''X 


Top Contestants ... 

Listed here are the Top Contestants for the Programmer’s 
Challenge, including evety'tine w ho has accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by tliis month's entrants. 


Rank 

Name 

Points 

Wins 

Total 



(24 mo) 

(24 mo) 

Points 

1, 

Munter, Ernst 

m 

y 

872 

2, 

Tdybc Joiiathm 

37 

2 

83 

3^ 

Stenger, Aten 

33 

I 

118 


Saxton. Tom 

32 

1 

210 

1 

Hiekcn, Willeke 

46 

2 

134 

6 . 

WihlijoiiJ, Claes 

40 

2 

49 

a 

Gregg, Xan 

20 

1 

140 

9 , 

MalleH, Jeff 

20 

1 

114 

10 . 

Qxijx^r, Tcmy 

20 

1 

20 

IL 

Tiuskier, Peter 

20 

t 

20 


voyi GDI YOGG NEW MAC. GREAINGW. ALE VGG WANT EG GO 
IS PGGEISH A SIMPLE. YEE ELEGANT WEGSITE. CA1AE0G ANO POSE YGGG 
PICEGGES. 00 SOME PGGEISGING. 00 A EinEE OGAWING. MAKE A LEW 
POE EIEES. AGCGIVE SOME OOCGMENTS EG SENG EG YOGG MOEGER. CGI 
OP SOME GGITONS EGG TGAI ELEGANT WEGSITE. ANIMATE TGEM. 


A TRACK ROW MGCG TIME 
II TOOK YOG EG 00II ALE. 
I ANO YOG WANT TO 00 
III EGG LESS EGAN S300. 



0 ^ m ^ ^ ^ ^ 

CfotA-* rineEquals SIbudMi 

Kkr raWh* Monty'' 

SIGH SIGHO'>200 1 

OOWNEOAO NOW OR PGRCGASE CO WWWSIDNE COM 

S70NE SrUDiOr 8 APFS THAT SET rOU FREE TO ORAIV, TWEAK, 
PROCESS mo PUBLISH YOUR IDEAS. ON WER OR ON I H£ WEB. 



























KACI SHOWCASE 


^ Sig Software 

NameCleaner 

An industrial-strength utility to manipulate file names 
and types, focused on preparing Macintosh files 
for use under Windows and Unix, and vice versa. 
Available with previewing, logging, scheduling 
and scripting ■ download a trial version from our 
website for OS 7/8/9 or OS X. 

www.sigsoftware.com 
Email: sales@5igs0ftware.com 



Keep track of every second of your time and bill 
for it with Time Track! Built in instructions make 
it easy to use. It is a simple way ta manage your 
billable time for multiple projects and create a 
web page to show to your clients. Only $24.95 
per single user license per plotform. Finally! A 
versatile time tracking solution for Macintosh, 
Windows, and Patrnl 


www.trinfinitysoftware.com 


InformlNIT 

The ultimate guide to the Classic Mac OS 
& the Classic Environment in Mac OS X 

5 Mke/Stars-Hacworld 
AuChoriCaCive. a Must Have-MacAddict 
Shareware of the Year-MacUser 
The idtimate troubteshooting gulde^ac Today 
The ultimate primer-ZDNet 

www.InformlNIT.com 


Eudora Internet Mail Server (EIMS) 
3.1 is the latest version of the most 
popular Internet mail server for the 
Macintosh, If you need to handle 
email for □ dozen users, or 
thousands of users, EIMS is a 
reliable and easy to use solution. 

EIMS 3J is available far USS400.00, ihere are no limits on the number of users 
thot can be added, and free email support is included. 

for more information, see 

http;//www,eudora.€0*nz/ 


GraphicConverier converts 
pictures to different 
formats. Also it contains 
many useful features for 
picture manipulation. 

See wwwJemkesoft.com 

for more information. 
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KACI SHOWCASE 



Watson 1.5 

Winner of the 2002 Apple Design Award for Most 
Innovative Mac OS X Product! An Aqua experience 
for the most useful Web services: TV & Movie Listings, 
Reference, Translation, Stocks, Flights, Packoge 
Tracking, and more. With an open architecture for 
third-party tools as weiL Download the demo now! 

www.karelia.com/wal'son 



By TLA Systems 

The Dock with more than one dimension. 

Create mu!tiple docks of any size, assign hot keys and 
even put the Trash back on the Desktop. A flexib!e and 
feature-laden tool for power-users. Runs natively on Mac 
OS X and 9 in five languages. 

. .you made the switch taOSXa ht easier hr me. „" - Bob LeVitus 

\..DragJhing can rigbthlly be (ailed an mdispensobie aid to working with yom 
MQc..”^Mocilserl}i( 

Download o copy now from www.dragthmg.com. 



Trapcode - plug-ins for Adobe® After Effects® 


Trapcode Shine is a fast light effect plug-in. The effect Icx^ks 
very much like volumetric light, but is actually a 2D effect. 
There are special controls to make shimmering lights and 
numerous coloring modes. This is an effect that you see 
everyday on TV and in many movie titles. Shine is available 
for Mac, Mac OSX and Windows. 


WWW. trapcode, com 


JktJotfmMt i^Mmamtosh Tkkn^ksyitrkvdiipmefti 



Got a great product sold through Kogi? 

Promote your product through the very cost 
effective Kogi Showcase in MocTech Magazine. 

For more information, contact us at 

adsates@mactech,com 
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AND THE Top Contestants Looking vor a Recent Win 
In order to give some recognition to other participants in the 
Challenge, we also list the liigh scores for contestants who have 
accumulated points witlioiit taking first place in a Challenge during 
ihe past two years, listed here are all of those contestants who 
have accumulated 6 or more points during the past two years* 


Rank 

Name 

Points 

Total 




(24 mo) 

Points 


- 

Sadebky, Gregory 

22 

24 


12, 

Schcrtsman, Jan 

16 

16 


13, 

Shearer, Rob 

1> 

62 


14. 

Hart Alun 

14 

39 


13. 

Boring, Kandy 

11 

144 


16. 

Nepsund, Ronald 

10 

37 


t7. 

Day, Mark 

10 

5(1 


m. 

Dest'h, Nimh 

10 

10 


19, 

Flowers. Sue 

10 

in 


20. 

Nioollc, ludovic 

7 

62 


21. 

Leshner, Will 

7 

7 


22. 

.Miller. Mik« 

7 

7 



There are three ways to earn points: (I) scoring in the top 
5 of any Challenge, (2) being the first person to find a hug in a 
published winning solution or, (31 being the first person to 
suggest a Challenge that 1 use. The points you c'an win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 points 

5th place 

2 points 

finding hug 

2 ix)ints 

.suggesting Challenge 

2 |>t^ints 


Here is Jonny's winning Disk Defragmeniation solution: 

PROGRAMMER s Defrag.cp 
Copyright © 2002 
Jonny Taylor 

// ^diide files omittctJ Ixit^^tLSe or leiigtli; sec tmlijie andiive 


/* The algorithm works as ftillows: 

Load tlx: irtformaLk^ Qoni tlie input file about wlim* on the disk Uie fntgmeius 
of Gidi file are to begin with 
Z. ChiKJse where disk we w'am eaeh file to end up 
X intdiigmC algorithm: w here possible, movt: Ihignienb to tlieir final positions 
with minitnal unneccssarv' rmn^es 

4, "Ciuaritnteeif algorithm: move am^ retraining fcigmenb to tlieir final pi^sitions 
whatever additiorial iTKwes iliis takes 

Three data sinittitres are useil by thest* algorithms. 

FreelCmge represenb a single contiguoi^v range of disk blocks tliai are not 
ciutemly occupied by any file fragment. Every Preefcinge is as large as possihle 
- i.e. it is not possible to have 

one FrecRangf fiir blocks 4-9 and another for 10-14 in e?dsT]ince at die same 
time 

Fraginent represents a single coniigiKHis nrnge disk blocks bt'kmging lo the 
same file 

HkLayout repiesents a single fik, and lias a lirdied Ust of all die fragments tliat 
make it up 


In addition, there are four search trees that are maintainedThese allow Fragments 
to be searched by current p^wition and by the final position that they will end up in, 
and allow Freefiitnecs to be searched by position and by letigth.The tree code is 
explained and implemetited mTrees.cp*but aO that really^ matters is that irtsertion, 
deletion and searching can be dtine in log(N) time. 

Ihene are quite a few nasty^ cases to the afgoritiims I have used, which need special 
treatment This is particnlaity true ftir the "guaiantctd" a^rithm because it must be 
able to handle anytliing at all. 

However for die mast pan die special cases are Itarxlled within a single function. 
Functions that perform tasks such as “move a block out of the way^wOI do what 
they are ddfined to do (theaigb ihey^ may be allowed to M), and will handle any' 
spetial cases tlietnselves. 

The solution is liiirly quick on reasonably complex test cases (suclt as test case 2 in 
dx: sample code). It slows down touglily lineitriy as the number of files and 
fragments on the disk increases,This results in unacetptabty long running times for 
very nasty test cases widi big disks full of tiny files. However 1 siLqxxi that any' 
solution would do dx: sanx:. 


struct FileLayout: 
struct Fragment: 
struct FreeRange: 

typedef struct FteoRange 

1 

long firstBlock; 
long lasTtBlock: 

Mode ‘posltlonTroGHode: 

Kode MongthTreeNode: 

// mediixl declarations omiltetl, se-e online sireliive 
I FreeRange: 

typedef struct FUeLayout 

I 

Fragment *firstFragitiont: 

Boolean placed; 
long fileLettgth: 

// methfKl ikTiaradons omined. see online archhe 
\ FileLayout: 


typedef struct Fragment 

\ 

long startBlock: 
long finalStartBlock: 
long numBlocks: 

Filel^yout * owningFile: 

Boa lean ItiFinalPoslt ion: 

Node *CurrentStarTTreeNnde; 
Node ‘finalStartTreeNodG: 
long firstFileBlock; 


Boolean blockedBySelf: 
long f ragraGntsBlockingTFLls; 


long processedlnThlsLoop: 
long score: 

Fragment *next; 

Fragment 'nextlnKoveList. 'prevInMoveLlst: 

Fragment *nGxtItiFlnalStartLlst * ’prevInFinalStartLlst: 
// metbixl ikcbmtions omitietl, see online jrdiive 
J Fragment; 


ifdefine kNotProcessed 
^define kMaxArraySize 
ffdefine AES(VAL) 
Ideflne HIH(A, B) 


-1 

32768 

{ (VAL) < 0 1 (VAL) : (VAIJ ) 
( (A) < (B) 7 (A) : (B) ) 


FileLayout *‘theFlles. * ‘unplacedFilesSortedByLength: 
PragniGnt ^'sortedFragmentList: 
r Sorted :tFniy of fnigmcTit pointers. 

Sort key viuies deperxiing oit w hich bit of code w'c nrv in 7 
Fragment ^firstFlnalStart; 

/* linked list of fragments, onlered by final stiri V 
Fragment ‘prevInList: 

/* (My used when setting up firstrutalSum 7 


extern DisplayType dlsplayprogress; 
extern AnimatlonType animationXype: 


/* Roots for the seareh trees V 
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O Another Myth Laid To Rest. 




ft has been a bng held theory that database independent data access (ODBC, JDBC OLE DB) provided inferior 


and inflexible database specific soJtJtions to serve your internal IS and external solutions. 


As the leading technology innovator and provider of Database Independent Data Access Middleware since 1992, 


OpenLink Sbfbvare has consistently^developed, deployed, and supported High-Performance ODBC, JDBC, and OLE DB 


Data providers that all^tate the pains associated with Database Specific Middleware and refute the claims associated 


With PLHFORMANCE,^ Empower your enterprise today by downloading a copy of the OpenLink Universal Data 


Access Drivers Suite from our Web site or call us at 781 273 0900 for more information. 


www.openlinksw.com 


PU^TFORM SUPPORT . 

MacOS Bi M aCOS X. Wl ndows 9^5y9S/Nr/2000/5<r; Linux, U nix (all flavors) 

G DATABASE ENOiNE SUPPORT FOR: _ / ; 

Progress^ bfiid^jyiicrosoft SdL D&/2, Informix). Sybase, G^’ingres arid other ODBC 

Compliant datable \ c 




CONNECT TO REMOTE DATABASE ENGINES WITH OR WITHOUT ADDITIONAL 
DATABASE VENDOR PROVIDED NETWORKING MI DDLEWARE 










Node ^fragmentCutrentStartRoot. *fraginentFiTialStartRoot ; 
Node ‘freeRangeLengthRoot. *f reeKangePoeitionRoot ^ 
r Gtneral globyJ variables V 

long totalFragments* totalBlocks, totalFiles. 
fragmentKPositloned; 

long uniqueSearchIndEXi firstFr&EBlock: 

r HeadH of linked lists of fragments that ane free to move to thdr final positions 

7 

Fragment •firstFragmentToMove. 

’* firstOverlapplngFragtQEntToMove: 

// function pfiotot)!^^ omitted, see cmline ait±ive 


Main Deftagmentation Code 

// i>oTests deleted for leogth, see online aiehive 

void Defragment (void) 

( 

// test case lotjp omitted ftir kngih^ see online archive 

totalFragments = 0i 
totalfllocks = 0; 
totalFiles " 0: 
fragmentaPoaitioned = 0; 
fragmentCurrentStartRoot " NULI_WQDE: 
fragmentFinalStartRoot = NULL_N0DE: 
freeRangeLengthRoot ^ NULl^NODE: 
freeRangePositlonRoot - NULL_NODE; 

// input li^c omitted lor lengtli, see tjnline arelmx* 

ChooseFllePositionsO : 

/* Rebuild the free range list to represent the aurunt Ilk piHatioas 
{iiistead of their final posiiisxis) 7 
firstFreeBlock ^ Ot 

InorderTreeWalk EfragiEGntCurrentStartRoot, 
BuildFreGRangeTtee): 

If (totalBlocks ■ 1 >” flratFreaBlock) 

new FreeRangG(fitatFreeBlockt totalBlocks * 1); 

t Move the Iragments to ilteir final positkms 7 
RearrangeFraginenta{ ): 

/* Release menH)ry7 

for {flleNun] = 0: fileNutn < totalFilesr fllcNutrH-) 
delete theFiles[fileNum); 

KillAliFreeRangefl(f reeRangeLengthRoot }: 

// test case completion tmutied fi>r lengdt^ set' utehive 

I 

void RearrangeFragments(vold) 

I 

Fragment ‘fragPtt; 

SetDeacriptionStringC^^Movlng fragpients {intelligent 
eigoclthni)" ) J 

for (fragPtr ^ firstFlnalStart^ fragPtr != NULL; 
fragPtr ” fragPtr->nextlnFinalStai:tListS 

( 

If C! fragPtr-MnFinal Posit ion) 

E 

r Check wliich fragments' FINAL R)Nmt>N is blot ked .si>ltly by the 
CURRENT ptjsiticjn of this one 7 
f r a gP t r->ForEve ryFr agmen tBlo c ked ByThisOn e( 
MarkFragmentAsBlockedEy)i 
f 
I 

firstFragmentToMovG = NULL; 
firstOverlapplngFraginentToMove = NULL: 

/* Rtsi do a check for fragnients that cun mine immetiiaiek Ui liit ir destination 
square* 7 

for (fragPtr = f iratFinalStart : fragPtr != NULL; fragPtr “ 
fragPtr‘>iie3ctlTiFinalSt art Li et) 

I 

if ((I fragPtr - ^inFinalFosltIon) 

(fragPtr *>fraj^mentsBlocklngThia = 0)) 

I 

f ragPtr->FreeToHoveTcFinalPosition t); 


I 

I 

MoveFragjaei^taTciDeStinationSquares C) : 
uniqueSearchIndex = 0: 

for CfragPtr = firstFinalStart; fragPtr != NULL: 
fragPtr = fragPtr - >nextInFinalStartList) 

Conside rMovln gF ra gmen t(fra gPt r); 

r ilTene will probably be fragnients left to reumnge (at least if live disk is densek 
populated). Switch to a simple, hut MsaJe.alg^irithm to place these remaining 
fira^ients V 
S etDes c ription S t ring( 

“Moving fragments (guaranteed algorithm)"): 
GuaranteedRearrangeO : 


void BuildFreeRangeTree (void *keyPtr) 
void KillAllFreeRangea [Node *x) 

// these nmtincs omitted Ibr length, see online archive 


(luK>sing File Ptisiticms 

r Befim: 1 actually mmi- any fragments, 1 decide what final ptjsitkm I want eadi file 
to end up in.V(t could just aim to ix>siti(m the first file at the siari of the disk, tlic 
next one immediately :ificT that, and so on. Howe'er in this problem tlus Is not a 
reqiurenient. Insitud we can clioose to pLice tlie files anywhere we want, as long as 
eudi iiKlmdual file Ls contigiKms. It is advanugeoiis to ehtwise a final position for 
as man>^ files :ls possible, such that one of its Ihigmenis is already^ in its fired 
pi/siritm. and di>eso’t have lo be mu\td at all. 

1 cant see an easy way of detc^nnining the (optimum file byout Instead I employ a 
gTLxdy algoridun, picking the fragment that kxjks best as the first “anchor" 
fnigmtTii. ami sti on. 1 experinvenied with several methods of scoring rath fragment 
as a poieotiuJ aneJujr, taking into accoum factors such as: 

Mietlierany tragnK'nis of the file ovedap ibeir final desiireition (a bad thing as 
llic>' then can't be moved In a single siqi) 

^ve-hedier anv^ otlar fragntents fmm the same file are also in their final positions 
<ag<H>d tiling) 

■ Ixjine attempt to tkiLTniine how much selecting tliis file would prevent us from 
seketing .several other files 

In the eodj didn't iHjtlier with this. Densely-populait'd disks are the ones dial take 
longest Ki solve, anti die mt>si moves tii re'timngr' In diose eases tlic limiting toor 
is the size of the frugmt'nts; a loige fiugmeni Ls likely tti lx* im|>ossible to nwive 
around intact, uthI will luivc m lx* spbt up to move it. I therefore' dedded to 
prioritise Lirge fragments when seleaing anclvirs. 

Incidentally: a final lactor, that 1 have not tried to uike inui ;tcxount at aO, is the size 
tif the free sp:iLt:s dial are left in tlte final layout. I suspect it would be l>etter to 
select a final layout with fewer, larger spaces since this makes it easieT to neammg 
die disk. 

t)nee i have sekcied ;ls many' ancimr fragments as 1 can, ilx're will prohihly be files 
left unplaced. I don't try :md tk) anything clever wiiJi these. 1 fust put them at die 
start of the largest empty space dial is available. I Inffirtunately. there is a proWtmi. 
t^KHising die anchor fragments means die remaining free space may Ire split into a 
numlrer of ninges. It may be impiKssible to fit die teniaiiiing files into the spacers 
(rememlrering the files must be contiguous). Even if it b po^sihle. it may not be 
possible to quickly find a valid layout.Tirere b no obvious way <jf seeing when we 
have chosen tm niany anchtw ftagments. Risteod, I use a binary search medxKl. I try 
placing as many andior fragnients jss I can, and see if 1 can posit itm the remaining 
files. If 1 can'L I ny widi Ivolf os many anchor fragments, and continue refining the 
value until 1 liave a reiLsonahle one. 7 

vol d Ch ooecF i 1 e Pos i 11 nns (void) 

I 

long filENum; 

Fragment *theFragi3jent: 

SetDescrlptianString("Choosing file positions'’); 

/* Sort the fregmenLs hy tlieir length 7 

qsott (sortedFragEflentList. totalFragments , slzeof (FragTiient ‘), 
Fragment: sQSCompareByLength); 

r Try ,...,,,,.7 

if [Arrang&FiiesWlthAnchorLlinit CtntalFllGs) = false) 

I 

long mlnimuiHAnchorCount = 0, maximumAncharCount ^ 
totalFiles 1 1; 
long, middle; 

DnplaceAll()■ 

for (long iter = 0; iter < 5: iter++) 
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middle (minimumAncliQrCqant maximumAnchorCount) / Z; 




I 


I 


if (ArrangeFilesWithAnchorLiinit(middle) true) 
minimiiniAn char Count =“ middle; 
else 

maxi mumAnch or Count = middle; 

If (max imumAnc hoc Count - mi nimumAiiohor Count = 1) 
break: 

UnplaceAll(); 

1 

if (middle != minimumAnchorCount) 

[ 

UnplaceAll(): 

ArrangeFllesWltbAncborLlmit{minimumAnchorCount); 

[ 

? 

t Nim wo haw sottM on on arninj^TTifm, huikl dio final start treo and linked list, 
tfccsiiLse tliJs tiToo rcjiiaifts sonic, we don'i aeiiMily need to do all ihe rudi.iLick 
insemionii.M^ could jiwt deterrainc the order and then build a balanced 
binary search tree by hand. However, doint; RBtrwert liir every fragment B fester 
dwi a quiekscirt of every fnignietit However ;iL we really need to do isi a 
quicksort of every file. If tlx: number t)f files Is leStS than half die number of 
fragments, it turns out it Is worth building the tree by liand.This will also lead t<^ 
a sligjujy betierlisilaneed uee, which will speed tip life seamhes a little. 

We alst) lake die opportunity to see which figments are alreaih i n their final 
position. If tliey are we maik diem as sudi; if they aren't dien we add tliem to the 
list of fragments CsoftedFiagmentList), which is ordered by fmal stort.Tliis linked 
list will temiiin static until we txime to the"guaranteetl algorithm ".at which point 
it may gmw as fragments ore split 7 

firstFinnlStart ^ MULL; 
prevInList = NULL: 

if {tQtalFrngments / totalFiles >“ 2) 

I 

/■ Sort the files by final fKisidon ;ind thereby sort the fragments V 
qsort(thoFiles, totalFiles, slzeof(FileLayout, 
FileLayont; :QSCompaireBy Final Start); 
long fragWum ^ 0: 

for (fileNum “ 0: fileNum < totalFiles: fileNum++3 
f 

for (thaFragment = theFiles[filaNum]■>firstFragmant; 
theFragment != NULL: 
theFragment ” tbeFragment->next) 

I 

sortedFragmentLlst [fragNum-l-+] = thoFragment: 
theFragment->ChecklfInFinalFositlon[): 


y" build the tree, given the sorted fragment list 7 
fragmentFinalStartRoot ^ 

BtLildBalancedTree (sortedFragmentList, 

0, total Fragment a - 1, Nl]LL_N0DE) : 

I 

else 

i 

for [fileNum = 0; fileNum < totalFlles: flleNmir^) 

I 

for (theFragment = theFllea tflleNum] ->firstFragment: 
theFragtiient NULL: 
theFragment ^ theFragnient->next) 
i 

ASSERT (theFragment->fiJialStartTreeNode = NULL): 

theFragment->CheckIfInFinalPosition(): 

theFragnient->flnalStartTre€Node = new Node: 
theFragiiient'> finals tar tTreeNode->dat a = theFragment: 
theFragtient - >f itialStactTreeNode * >keyLong = 
thsFragment->finalStartBlock: 
theFragment - >f inal StartTreeNode- >keyaNcid 0 Pt r = 
fictheFragment- >finalStartTreGNode: 

RBInsert (&fragmentFinalStartRoot, 
theFragment->finaIStartTreeNod e): 

J 

I 
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Node *BuiIdBalancedTreeCFragment ** fragLlst. long first, 
long last, Node 'parent] 

// this routine omined for length, see iraline archive 

Boolean ArrangeFilesWlthAnchorLimt (long maxAnchors) 

I 

long fileNuffl. fragt 
long nuuiUnplacedFiles = 0; 

t Attempt to come up witli a Ble arrangement that uses up to maxAnchoR andnir 
fmgnients 7 

r We start with no file positions cliosen.atKl the wlioJe disk available 7 
new FreeRangeCO. totalBlocks - 1): 

r We shcjukl be able to Jeait some fnagments where tlvey arc. and build up anninti 
tlicm the file that they arc part of. I choose the Lugesi fragments as a priority, 
since they wifi be haniest to move around when we arc rcarrangir^ the disk. 

This is not always ideal ftjf example, picking ilie largesi fragment might prevent 
us from picking a kige number of sli^dy smaller ones. How^c^'er it is the only 
quic-k and simpk way that 1 ctJuM &id 7 
long nuntPlaced ^ 0; 
for (frag “ totaXFragments ■ Iv 

[frng >= 0) && (numPIaced < maxAnchors )i frag^} 

t 

Fragment *fragPtr " sortedFtagmentLlst[frag] : 

r sortedFnigmenilist is airrcntly s()rted by leiigth 7 
FileLayout 'owningFile = fragPtr->owningFile: 

if (j □vningFxle‘>placed) 

i 

r This file has rxit been assigned a position yet (lic-ck if any other files we 
have alrcady^ pcisitioned arc blocking tills position 7 
FreeRange 'rangeAtStart - 

(FreeRange’]DATA(TreeSearch(freeRangePositionRaot, 
ragPt r->firstFileBlock, 

FreeRange::FindRangeContainlngBlock]): 
if (rangeAtStart->laatBlock >“ 

fragPtr->firstFileBlock + QwnlngFile’>fileLength - 1) 

I 

/* llierc is no file bliK king this p<isiii<in 7 
owningFile->placed ” true: 
owningFile * >SetFinalPoaition(rangeAtStart < 
fragPtr->flrstFllefllock): 
nu]iiPlaced++; 

1 

1 

1 

r Wc now^ prolxibly^ ha\e some files kdi i wen to try and fit into the gaps that arc* 
left. My heuristic herc Ls to sum with the hrgesi lik*. and pLiee it in tile largest 
gap availablc.Thb Is far from kleai,bui I suspect that finding the optimum 
solution is an EvtPcompleie problem (similar to sack-filling pmblems>,MJ Tm not 
iiKj boihercdl 7 

/* Sort the unplaced files in otder of total lenjJth 7 

for (fileNum = 0: flleNum < totalFUes; fileNUTii++) 

f 

if {! theFiles IfileNutn] ->plated) 

[ 

unplacedFilesSortedByLength [nuntUnplacedFlIes] = 
theFiles [fileNum] ; 
riumtJnplacedFiles-H -1 

\ 

\ 

qsort(unplacEdFilenSortedByLength, numUnplacedFiles, 

fllzeof(Fi1eLayout'), FileLayout;:QSCompareByLength)i 

for [filefJuin = numUnplacedFiles - 1: fileNum 0: fileNum- 

{ 

FreeRange 'chosetiPosltion - 

(FreeRange') DATA CTreeMaxiiiiura{freeRangeLeFigthRoQt)) ; 
if (chosenPosltlon* >lasi:Block * chosenPositiDn->firstBlock 

+ I 

< unplacedFilesSortedByLength[fileNum] - 

>fileLength) 

chosenPosition = NULL: 

if (chosenPosition l= NULL) 

I 

r Position tlie file at the start of tl^e free range we have sektied 7 
unpiacedFilesSortedByLength [ 

fileNum] - >SetFiiialPosition (chose iiPoeit ion * 


ehosenPo5ition->flrsiLBlock); 

1 

else 

f 

r Failed to position the file. Break out immediately 7 
break: 

I 


y* Delete all the free rangR and their search trees. Ether we arc going to restart the 
algorithm, or we are going to move on to tlie next phase. &>r which we need the 
INITIAL trce ranges, rather than the FINAL ones 7 
KllIAllFreeRanges (f reeRangeLengthRoot): 
freeRangeLengthRoot ” NULLJNODE; 
f reeRangePosltionRoot = NULL_N00E: 

if (fileNum >= 0) 

E 

f We didn't manage to potsiTion all the files 7 
return(false): 

I 

return(true) : 

} 

void FileLayout: :SotFinalPosition(FreeRange 'TangeToPlaceIn, 
long flnalStartBlock) 

I 

for {Fragment 'theFragment = firstFragment: 
theFragment !=^ NULL: 
theFragmant = theFragment->next) 

( 

theFragment’>flnalStartBlock ^ flnalStartBlock; 
finalStartBlock ^ theFragment->nuiiiBlocks; 

I 

rangeToPlaceln- >RangeNotFree {f i rstFragment * >f InalStartBlock, 
fileLength): 

I 

void Fragment: :ChcckIfTnFtnalPositioti(void) 
void UnplaceAll(void) 

// tlicse routines omitted for lengt h, sec outme archive 

" ('ruarantced" Algorithm 

r We work thrt>iigh the fragments that have not yet been moved to their final 
(^>osjtions. For eadi £>ne,ck*ar any bkieking fragmeoLs (joi of tlie way and move U to 
where they were. 

Tills algoritlun must lie alile to cope with all siruaiions.This means that special 
lundling Ls necessary when temporary^ storage Lisewberc tm the disk is limited, and 
wIkti the fragnieni partially mviiaps its final ptssirion V 

// tills section deleted Rj^r length, see online archive 

”InielliKnit''Alg^iritbm 

r The idt'i is to ideotily' fragments that, if moved,allow antitber fragment to lx* 
moved to its tlestination.Hopefulh; moving that fragment to its destination frees up 
the space that lUMJtlier fragmem needs to move into. :ind so on. R^r a disk with a 
reasonable amount tif free space (around lialf), this will move neiirly all of the 
fragments. Bar a di.sk witli a very small atnouni of Irce s|)ace, it will generaJJy 
work very weU. 

Each fragHKnt keeps tn*ek of how many iither IragntenLs arc* blocking it trom being 
nxjved to its final jXKdtkm 

I. Erxl a fragment that is bkickcii by <mly ime other fragment 
I ,See if it Is possiNe to move tlnii blocking Eragntent somewhere else 
5. fiTHAT fragment could be m<jved to its destioadoTi were it not ftir orrc single 
fragment blocking it. then repeat as man) times as |Xjssd>le until we end up with a 
bicxking fragment we can't move to its final destination 

4. Move that fragment some where out of the way 

5. I Ipdate the blockage infi urination as a result of the rntwe 

6. While dverc arc iinblixked fragments, move tlieni to their dt*stinations, updating 
dve l5lcx:kagc inftmiLition again 

Tliere arc tw> pniWems with this strategy. Wd migin end up covering the same 
ground several times. If we conskkT a long ckiin t>f dependendes beforc giving up, 
we miglu follow tkit dwin each time we eixoiimeted {xie of iLs members. Also, it Ls 
possible to have a drcular dependency' drain wherc every' fragment is waiting kir 
the next one in the loop. Under those circumstances we might end up ftrllowrag the 
drain round and round for ever.To avoid both these cases 1 fill in the unique search 
index' when I first pnxess a fragment, tf I come actv)!S a search index smaller than 
the ciarent one, I abort die searcli.Tlus Ls not very elegant, but it wodsslV 
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void ConsiderMovingFragraent(Fragment ‘fragPtr) 

t 

if C(!fragPtr->inEinalPosition) && 

(fragPtr->fragpjentsBlockingTiTis <= 1} && 

{fcagPtr OprocessedlnThisLoop = kNotPri>cesaed)) 

[ 

r Thb ftagnietjt is «ne to wc lo be alik- to move 7 
Fragment ^fragToMove = fragFtr: 

FreeRange*longestRangePtr = (FreeRange*)(TreeMaximuniJ 
freeRangeLengthKoot)‘>data); 
long longestFreeRange ^ longeatRangePtr->laatBlock - 
loiigeatRangePtr->firatBlock + Ir 

/• (ijvco the fragment that we want to mmt. find the one that is bJoddng it. 
Gieck if that fragment can be moved ...... continue tkscripdon..„..V 

uniqu e S ea rcbInd ex++ j 

fragPtr->processedIriThisLoop “ uniqneSearchlndGK: 

do 

i 

/* Find the fragment bltjddng to one V 
Fragment ‘result = (FragjnEnt’)DATA(TreeSearch( 
fragmentCurrentStartRoot, fragToHove♦ 

Fragment::FlndOneBlockingTheKeyFragment}): 

ASEKRTt result E= mL): 

r If therc isn’t anywhea- we can move that ftagmoit tOn stop now V 
if (tesult‘)numBlocks > iongestFreeRanae) 
break; 

r l*nK’essed in a pa-vkius loop, or afready in liiis kjop {in whidi case we have 
found a ring wl^ie every fragment Ls paventing the next one from being 
niKJved - moving imj' of tose wili alkjw alt lo he moved <xk' after the other). 
Stop the search 7 

if {(result->proeessedlnThisLoop <“ imlqueSearchrndex) 
{result->processedInThlsLoop != kNotProcessed)) 

1 

break: 

} 

/* If we move a^uli' we will lx: al>k- to move ‘fragToMove’ into the space it 
lias 

left 7 

fragToMove “ result: 

fragToMave->proesssedlnThlsLt3op * unlqueSGarcblndex; 

r !f we get to a fragment to b bkxircd by nwia^ diaji one, we h;ive reached 
the end of die diain. Stop to kiop, 7 
I while CfragToMove->fragiiiGntflBlocklngThie = 1); 

if ({fragToMove “ fragFtr) && 

{fragToMove->fragjnentsBlocklngThis 0)) 
return: /* Failed to find a place to move Lbc one blocking ii 

V 

if ((fragToMove-kprocessedInThisLoap < unlqueSearcblndex) 
45 . 

(fragToMove->processedInThisLoop E^ kKotProcessed)) 

I 

return: /* AJjready pnx-cssed KirUcr 7 

I 

r Now we have dedded on a fragment to move, make Ux- move.We should iiave 
diecked eariici- im that theie a suitalile spaee to move to* Jragmeni into. If we 
arc very unlucky, thoitgh,the new^ space we select will still he hiticking the 
rangr' we arc trying to to, so the call Isn't ItKl^X. guaranicTtl to alkiw any other 
fragments to nxive 7 
fragToMova->H oveOu tOfTheWay(}: 

MoveFragment sToDnstinationSquares(); 

I 

I 

void MsrkFragraentAsBlockedBy(Fragment •theBlockedFragment, 

Fra gaen t ‘t heB 1ocke r] 

// this routine omitted for lengtii, see online archive 

void HoveFragmentsToDestinatiouSquares Evoid) 

[ 

r While therc arc' fragments queued as tvady to mcw.%mov'e ihcmi to theirftnal 
dcsimatioffij. Moving one fragment maj arid extra fr^jments to liie lists. Mming 
it may occasionally block one of the other fragments to arc queued. In that case, 
die fr^ient b femoved from die queue auiomaticallyV 
Fragiaeut ‘fragToHove: 
do 


I 

while EfirstOverlappingFraginentToMQve 1“ NULL) 

I 

fragToMove ^ firstOverlappingFragmentToMove: 
fragToHove->ReiiioveFrotnListsC): 

fragToHove' >KoveToFiTial0verlappingPo3ition(t rue) : 

1 

while (firatFragmentToMove 1= NULL) 

f 

fragToMove = firstFragmentToMove: 
fragToHove'>ReraoveFromLlsts(): 
fragToHove '>MQveTtiFiaa 1 Position (true); 

J 

I while (firstOverlappingFragmentToMove 1“ NULL): 


void Fragment : :FcirEveryFragnientBlockedByThisOr>eE 

void (‘theCallback)(Fragment ‘theBlockedFragment* 

Fragment *theBlocker)) 
void Fragment::FragmentAboutToUnblock( 

Fragment •theBlockedFragment* Fragment ‘theBlocker) 
void Fragment::FragmentAboutToBlock(Fragment 
•theBlockedFragment, 

Fra gmen t * theB1o eke r) 

// dicsf routines omitted for kngtli, see online archhe 

void Fragment: :FrecToMoveToFinalPoaiTlon[vold) 

[ 

/* This function is called when there is nothing preventing the fragment from 
nKivingto its final position.VW: do not immediately move the fragmeni* though - 
we just ^ ^ to die relevant queue so it will be moved in fix next call to 
MtnuFragnxmtsTofk'stto^^ function was pttibably called 

because aniiiher fragment Ls about to move, unblocking this fragment's final 
position.Tlmt fragment mi^t move to a new position tliat is STILL hkxking tos 
fragment, Uiougli* so we will 
have to wait before we acUially' move this fragment 7 

ASSERT(nextInMoveList -= NULL): 

ASSERT(prevInMoveList “ NULL): 

If (blockedBySelf) 

1 

/* fragmeni is only hkieked by iLself Add it u> tlx list of (xxs to move. 

Tlierc is a separate list for dicix* as we migjit want to w:iit for a Ngger gap to 
lie 

availUik* as temptirary storagi' 7 
nexTinMoveList " flrstOverlappingFragmeutToMove: 
nextInKoveL±et'>ptevIiiMoveLlst ” this: 
pruvltiMoveList = NULL: 
firstOverlappingFragmentToMDve “ this: 

I 

else 

I 

/* tnn lx movetl directh' to final position 7 
nextlriMoveList = f irstFragmmitTciMovs: 
nextInMoveList->prevInHoveList = this; 
ptevInMoveList “ NULL: 
firstFragmentToMove - this: 

} 

I 

void Fragment::RemoveFromLists(void) 

// this routine omitted fix length* sec online arcliivu 


Miiving Ft^agnienis 

void Fragment::HoveToPosition(long destBlock, Boolean 
maijitfl inB I Dckage Count) 

I 

r Mtwe the fragment as iastrucietfand inform any interested parties 7 
r Vtb may want lo keep track of which fiagnxnts :iie hdng bitxked at to moment. 

lfst)jnaintiiinBlock;igeO>unt is'true' 7 
if (maintairkBlockageCount) 

I 

r Inform tjilier fragments that this fragment'.s airrciit positkin is :ibout to 
become 

to' V 

ForEveryFr a gment Blocked By ThlsOne (FragmentAboutToUnblock): 

I 

r jMark to place it was as free 7 
FreeRange: :FragiiientRangeIsFree(thls): 

OutpUtMovelnstnjctiqnEstartBiock, desLBiock* tiumBiocks, 
inFinal Posit ion); 
startBlock = destBlock; 
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t Wf might havTf moved it to its finaJ destination by chance */ 

If {startBlock = finalStartBlock) 
inFinalPositlon = true; 

/* Do the sL'uidatd processing for when a fhgjitent has moved 7 

Fragment Ha sMoved (ma int a InE lockage Count J: 


void Fragment: :MoveTciPositionNoOutput[long destBlock) 

// tills rtJUUne omitted for fengtli, sec online archWc 

void Fragment;:MoveOutOfThaWay(void) 

// this routine omitted for length, sec online archive 

void Fragment:iMoveToFlnalPosition(Boolean 
main t ain£1oc kageCount) 

// this routine omitted for lengtli, see online arclih'e 

void Fragment: :MoveToFinalOverlappingPasition(Boolean 
maint ainBlo cka geConnt) 

I 

/* We ^^ant to fold the most efficient way cif making the move. Because the souiee 
and destination ranges arc not alkrwcd to overiap fijr a move instniction, it cannot 
be done with a sin^e instruction.We could ettlier move it somcwlieic ccmipletdy 
different and foen hack to its destination, or we ci>uld mow it in several chunks, 
hut without using any ottia tcmponi^^ storage This Lh treated as a spedal case 
IX-T-'ausc there are severai ways of ckMng it, and a number of nasty catdies we need 
to check for V 

ASSERTEfragment^BlockingThis ^ 0): 

ASSERTCblDckedBySelf): 

long moveiment = ABStstartBlock finalStartBlock); 
long blocksAvailable* firstBlockAvailable : 

r Sian by working out how many steps it would take to move the fhgmem widwut 
using any extra temporary sturagie Xlileolate noriiBkjcks/mtftement. rour^ed IJP 

V 

FreeRange‘bestRange = NULL: 

long bestSteps ^ tnumBlocks + movement - U / moveinent: 
long b 1ocksAvailableInBestRange, 

f1r a tB1ockAvailab1eInBes t Ra nge: 
long steps: 

If (baBtSteps > 2) 

I 

r Wt wjdd take at least two surps to move the rragmeni via any extra space we 
might chotise, st> only^ consider otlier options if we can't do it in twr) moves 7 

r Find the biggest space available, and see how many steps it would take to 

move 

the fr^jment via iL Note that this largest ninge mat be the one that ineluiks 
the 

desiimtion area, in which case not all 
of it is av'ailable as temporary^ storage' 7 
FreeRangc'largestFreeRange = 

{FreeRange*)DATAETreeHaxtmuin EfreeRangeLengthRciot)): 

if ((startBlock > finalStartBlock) hi, 

Elarge5tFreeRange->lastBlock “ startBlock ^ 1)) 
f 

/* Overiap between source and dest fragment positions is at the end tif the 
dcstination.and tweriap with this ffee range Is at the start of tile destination 

7 

blocksAvailable = finalStartBlock * 
largestFreeRange->fir3tBloek; 
firstBlockAvailablE = largestFrecRangeOflrstBlock; 

1 

else if {(startBlcck < finalStartBlock) && 

{largestFreeRaiige*>flrstBlock ““ startBlack + 
nimBlocks)) 

I 

/* Clvcriap with existing hragment posititm Is at tlie start of iJic destination, :md 
overiap with the free range is at tlie end of die destination 7 
blocksAvailablc = iargcatFteeRange-HaetBlock - 
(finalStartBlock + nuitiBlocks) + 1; 
flrstBlockAvallahle = finalStartBlock + numBlocks: 

1 

else 

I 

/• The ffee range we have foimd is somewhere completely' diffeTent (the klral 
ca!«!) 7 

blocksAvaliable = largeBtFreeRange‘>laBtfllQck - 


large^tFreeRange‘>firstBlock + 1; 
firstBlockAvailable - largestFreeRange~>firstBlock: 

I 

if (blockaAvailable >0) 

I 

/* Work out how many steps it mjuid take to transfer il>e whole ftagment. 

Calciiiaie 2 * (numBiocks / blocksAvailable, rounded UP) 7 
steps = 2 • ( EnuinBlccks + blocksAvailable - 1) / 
blocksAvaliable): 

if (steps < bestSteps) 

i 

/• IhLs is the best option stifar 7 

bestSteps “ steps: 

bestRange = largestFreeRange; 

blocksAvailableInBestRange " blocksAvatlable: 

firstBlockAvailableInBestHange = firstBlockAvailable; 

I 

If (blocksAvailable !” largesl:FreeRange->lastBlock - 
largGStFtecRange’>flrstBlock + 1) 

I 

r TiU' range we just looked at is tile one that includes \hc desimation 
pusition.lhLs has been taken into mtiunt in the calculations we just 

made 

to rate it. However, tliis means that du^ secondrhrgtst free nu-^ge may 
actuaih' l>e a Ixtter choice. Note that since the last range we considered 
overLipped the destination, we know this 
one doesn't 7 

largestFreeRange " {FreERange*) DATACTreePredecessor( 
largestFrGeRange->lengthTreGNode}): 
blocksAvailable = largestFreeRange->lastBloek - 
largestFreeRange->firstBlock + 1; 

/* Caktihie 2 ’ (num Bl( icks / bkx:ksAvailahle. rounded IFP) V 

steps ^ (2 * ({numBiocks + blocksAvailable ' 1) / 
blocksAvailable)); 

if (steps < bestSteps) 

I 

/* Ibis is die best option so far 7 
bestSteps = steps: 
bestRange ” largestFreeRange; 
blockfiAvailableInBestKange = blockaAvailahle: 
firstBlockAvailablelnBestRange = 
largeEtFreeRange->firstBlock; 

I 

1 

1 

1 

long offset♦ blocksToMoveThisTime. 
blocksAlreadyMoved “ 0, 
blocksLeftToMove = numBiocks: 

if (bestRange ^ MULL) 

I 

/* The best witv' of moving it doesn’t uhc uny' mldiUonal sttrrage We move as 
much wt' can in one gp, and this frees up anotlier section that can be 

moved, 

until die whole fragment has been tnovxxl 7 

r Starting (tom Uic end of die fragment, move it in chunks of si/e"movement" 
to its final pt^iUon 7 
while (blocksLeftToMove > 0} 

I 

blocksTDMDveThisTime ^ MIN(movement* blocksLeftToMove): 
if (finalStartBlock > startBlock) 

offset = numBiocks * blocksAlreadyHoved - 
blocksToHoyeThisTime: 

else 

offset blocksAlreadyKoved; 

OutputMovelnetmction (startBlock + offset* 

finalStartBlock + offset* blocksToMoveThisTime, 

true); 

blocksAlreadyMoved ^ blocksToMoveThisTime; 
blocksLeftToMove " bloeksToMovEThisTlme; 

I 

I 

else 
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{ 

r Hie best wjy of moving it is to move as mudi as fwjssibie into bestRange, and 
from iliere to its final fH>sitk>n, repeating until the i^-hole fragment has been 
mcived 7 

r Starting from tlie end of the fnigment, move it in ditinks of size 
“WtH:ksAviiilabk[nBestRange"t<j its final p wit ion via 
fii;sLBkx:Mvad:iblcIfilk^tHai^ 7 
while CblocksLeftToMove > 0) 

( 

blpcksToMoveThlsTime = MIN(blocksAvailableInBestRange, 
blocksLeftToHove); 
if CfinalStartBlock > startBlock) 

offset = ntiraBlocks - blocksAlreadyHoved - 
blocksToMoveThisTirae i 

else 

offset = blocksAlreadyMoved: 

OutputMoveInstructicni(startBlock + offset, 
f i rs t Bio c kA vai 1 ab 1 e InB es t Ran ge ♦ 

blocksToMoveXhisTime* false): 
OutputMovelnstniction [flrstBlockAvallablelnBestRange. 
finalStartBlock + offset, 

blocksToMoveThisTinie, true) j 

BlocksAlreadyMoved -l-= blocksToMoveThisTime; 
blocksLeftTobfove -= blocksToMoveThisTirae; 


1 

r Update the internal information to take aL'tonm of tJiLs move (it doesn't maner 
exactly how we adikvetl the move).Also notify^ an>' other fragments afifected hy 
the mtive, sfj tht7 can update 
their blockage counts 7 
inFinalPosltion = true; 
if (iBaintainBlockageCount) 

ForEveryFragmentBlDckedByThlsOns (FraginentAbQUtToUnblacJt) : 
FrenRange: :FragfflentRangeIsFrse(tMfl) ; 

EtartBlock “ finalStartBlock: 
if (maintainBlockageCoutit) 
blockedBySelf = false: 
fragmentsPosltioned-H-; 
if {(displayProgress = kDisplayBlocks) 

(animationType 1= kFastestAnlmatlon)) 

I 

UpdateProgress({(float)(testCase -1)+ 

C(float)fragmentsPosltioned / (float)totalFragments)) / 
(float)numTestCases, testCass): 

I 

r No need to leson tlic current-position tree as li-n: fragment order hasn’t changed. 

vet do need to update its sort key dioughV 
currentStartTreeNode->keyLcing = startBlocki 

if [uiaintainBlockageCount} 

ForEveryFragmentBlockedByThlsOne[FragniGTitAboutToBlock): 
FreeRange; :FragiiientRangeNot Free (this): 


void Fragment::FraginentHasMoved{Boolean raaintainBlockageCount) 
// this routine omitted for lengtli, see online archive 

Fragment ‘Fra^srit:; SplitToFitLeEgth(loiig lengthOfFirstPart) 

// this routine omitted for length, see online ardbive 

void OiitputMoveInstruction(long from, long to. long 
blocksToMove, Boolean finalPosition) 

i 

If (displayProgress = kDisplayBlocks) 

ClearDisplayedBlockRangs{from, from + blocksToMove - 1): 
fprintfCoutputFile* "%ld.%ld,%ld\n". from. to. 
blocksToMovG); 

if (dlaplayProgreSB = kDisplayBlocks) 

SetDispiayedBiockRange(to, to + blocksToMove - 1, true. 
finalFosItion): 

1 

// Search function section omitted for kmgth, see online archive 

// Main.cp, ReatlExistingxp.llees.cp,Trees,h, Windows.cp omitted because of 
// Icngtlt; see online archive 
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QUICKTIME 

TOOLKIT 


hy Tim Monroe 


Trading Places 


Working with Alternate Tracks and 
Alternate Movies 

iNTRODlfCnON 

QuickTime's original designers understood very clearly 
dial QuickTime movies would be played back in quite varied 
environments — on monitors with different pixel depths, tin 
faster or slower machines, in Quebec or in Cupertino, They 
developed a mechanism by which QuickTime can choose 
one track from a group of tracks in a movie according to 
some characteristic of the playback environment. For 
instance, a movie might contain two sound tracks, one with 
an English narration and one with a French narration. At 
playback time, QuickTime selects the sound track whose 
language code matches that of the current operating system. 

The group of tracks from wdiich QuickTime selects is 
called an allernaiif track grouf), and a track in this group is 
called an alternaie track An alternate track is selected based 
on the language of tlie track's media or the quality of the 
track's media. The media quality is a relative indication of the 
track's sound or video quality (poor, good, better, or best). In 
addition, for visual media type.s, this media quality can 
specify which pixel depths for which the track is appropriate. 
Alternate track groups provide a .simple hill effective way lo 
tailor a QuickTime movie for playback in different languages 
and on computers with different sound and video hardw^are. 

QuickTime 3 introduced a way to tailor the movie data 
displayed to the user according to a much wider array of 
environmental characteristics, including the speed of the user’s 
connection to the Internet, the version of QuickTime that is 
installed on the user's machine, and the availability or version 
of certain software components. This magic is accomplished 
not wilh alternate tracks but with ultarnate movies. An 
alternate movie is any one of a set of movies ihai contain 
media data appropriate for a specific characteristic or set of 
characteristics. For instance, one alternate movie might contain 
highly-compressed video and monophonic sound, w^hile a 
second alternate movie contains higher-quality video and 


stereo sound. Because it is smaller in size, the first alternate 
movie woukl be appropriate for users wilh relatively slow 
Internet connections; the second movie would be appropriate 
For users wath faster Internet connections. Similarly, one 
alternate movie might be appropriate for playback under 
QuickTime 6 and another might be appropriate for playback 
under all earlier versions of QuickTime. 

Alternate movies are associated with one another using a 
movie file that ctmiains data references to all of the alternate 
movies as well as information about the criteria by which 
QuickTime should select one of tho.se alternaie movies when 
chat movie file is opened. This other movie file is called an 
aUernate reference movie file (or, more briefly, a refermce 
movie), since it refers lo a set of alternate movies. When the 
principal selection criterion is the users Internet connection 
speed, this movie is sometimes also called an alternate data 
rate movie. 

In this article, we’re going to take a look at alternate 
tracks and alternate movies. Well see how to create alternate 
track groups in a movie and how to interact with QuickTime's 
aitermue track selection either programmatically or using 
wired actions. Then we’ll see how to create alternate 
reference movie files. 

Alternate Tracks 

As we’ve seen, tracks in a movie can be sorted into 
alternate track groups. At any time, at most one track in an 
alternate track group is enabled and the remaining tracks in 
the group are disabled. This enabling and disabling is called 
atilo-aUernaiing and is performed automatically by the 
Movie Toolbox, based either on the language of the tracks or 
the quality of the tracks. Tracks tn an alternate track group 
can he of the same type (for ex^miple, all video tracks) or 
they can be of different types. Figure 1 shows a frame of a 
movie played on a ct>mputer with English system software. 
Figure 2 show.s a frame of the very same movie when played 
on a computer with French system software. This movie 
contains two text tracks that are grouped into an aliernate 
track group. 


Tim Monroe in a member of the QuickTime engineering ream Ymi can rnnfarr him at monroc^appk'.com. The views expre.ssed here are not 
necessarily shared by his employer. 
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Figure 1: An English aUernale track 
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Figure 2: A French aliemate track 

The Movie Ttx)]box provides about a dozen functions that 
we can use to work with alternate groups and with a media’s 
language and quality. For instance, we can use these functions to 
create an alternate track group in a movie and to dynamically 
switch languages during movie playback. We am also use tliese 
functions to control QuickTime’s alternate track selection 
process. We'll exercise some of these functions by adding a pop¬ 
up menu to the controller bar that allows the user to selea from 
among the languages used in tiie movie. Figure 3 show^s tills 
pop-up menu at work. 



Figure The custom pop-up ianguage menu 


Getting and Setting a Media's Language 

A media’s language Is specified using a 16-bit language code. 
(Tliis is also sometimes called the region code.) Here are a tew' of 
the language codes defined in the header file Script,h: 

eTnim 1 

langEnglish = 0, 

langFrencli = 1, 

IangGerroan = 2, 

langltalian - 3, 
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langDutch 

= 4. 

langSvedish 

- 5. 

langSpanish 

= &. 

langUanish 

= 7. 

langPortuguass 

= B. 

langNorwegian 

- 9. 

langHebrew 

= 10 

langJapanese 

= 11 


When we create a new media (typically by calling 
NewTrackMedia), the language ii> set to 0, or langEnglish. We can, 
however, change the language by calling SetMediaLanguage. To 
set a media’s language to French, we could use this line of code: 

SetMediaLanguage(myMedla, langFrench): 

When the movie’s metadata is written to the movie file (typically 
by calling AddMovieResource or UpdateMovieResource), the 
language setting is saved in an atom (in particular, in the media 
header atom). 

At playback lime, we can call die GetMediaLanguage function 
to determine the language of a track’s media, like this: 

myLanguage ^ GetMe<iiaLanguage{iuyMedia): 

Listing 1 defines a function that calls GetyediaLanguage for eadi 
track in a movie, to determine which languages are used in a movie. 
If a language Ls used in the movie, the corresponding element in die 
array fLanguageMask Is set to 1. (Well u.se this army to determine 
which languages to put into our CTJstom pop-up menu.) 

listing 1: Finding languages used in a movie 

(^TAtt_l I pdatt Mov icLanguageMask 

static OSEtr QtAlt_UpdateMovieLaiiguageMask 
(WindowObject theWindowObject) 

t 

AppllcationDatHHdl rayAppData “ NULL: 

Movie ttiyMovie = NULL: 

Track myTrack "= NULL: 

Media rayHedla “ NULL: 

short myTtackCount, rayIndex: 

OSErr rayErr = noErr: 

myAppData = (ApplicationEataHdl} 

QTFraine_GetAppDataFroraWind owOb ject(theWind owObj set): 
if (rayAppData ^ NULL) 
return(paramErr): 

myNovie “ [*‘theWindowObject).fMovie: 

If (tpyMovie = NULL} 
return(paramErr): 

// clear ciui the existing mask 

for Cray Index = 0: my Index ( kNuniLanguages: raylndex++) 

( * *niyAppData} .fLanguageMask [rayIndex] - 0: 

// gel rhe language of each track in ihc movie 
niyTrackCount = GetMovieTrackCount (jiiyMovle): 
for [ray Index ” 1: ray Index rayTrackCount: myljidex’H-} [ 
rayTrack = GetMovlelndTrackCrayMovle, iityindex): 
if (rayTrack 1= NULL) ( 

short iiryLanguage: 

myMedia = GetTrackHedia[myTrack): 

rayLanguage ^ GetHediaLanguage(rayHedia3 : 

if t [rayLanguage )= 0) (myLatiguage ( kNuraLanguageaJ} 

C * * myAppD a t a).f Lan guag eMask[myLanguage1=1: 

) 

I 

return(raySrr)r 

I 


Nodee that we use the language code as the index into the 
fLanguageMask array. Tliis allows us to walk through that array to 
find the items that should be in the language pop-up menu, as 
illustrated by the QTAtt_GetMenyItemI ndexForLanguageCode 
function (defined in Listing 2). 

Listing 2: Finding a menu item index for a given language 

QTAIlG eiMcn lit If m IndcxFofU nguagt'C k 1 t 
inn116 QTAlt_GetMenu11emindexForLanguageCode 

(WindowObject theWindowObject, sLart tbeCode) 

( 

AppliestionOstaHdl myAppQata = NULL: 
abort rayCouiit = 0; 

short ray Index = 0: 

myAppDsta = (ApplicationDataHdl) 

QTFrame_GetAppBataFroraWlndowObject[theWindowObject): 
if [myAppData ^ NULL) 
return[myIndex); 

QTAl t_U pdat eMo vleLa n gua geMa sk(the Wind owObj e c t); 

for [rayCount * 0; rayCount <“ tbeCode: rayCount++3 I 
if ((“'rayAppData).fLanguageMask[rayCount] ^ 13 
raylndex++: 

I 

return(myIndex); 

) 


Getting and Setting a Media's Quality 

A track's tiiediu also has a quality, which Ls specified using a 
16-bit value. Figure 4 shows liow this value is interpreted, 



quality pixel depth 


Figure 4: A media qualif y value 


llie liigh-order byte is currently unused. Bits 6 and 7 of the low- 
order byte represent a relative quality. The Movie Toolbox 
defines these constants that we can use to gel the relative quality 
from the entire quality value: 


enura I 

rae diaQualityDr af t 
ra0dlaQualityNo rraal 
raediaQuaiityB e 11 e r 
raedlnQualityBeat 


= OxOOOD, 

- 0x0040, 

- OxOOSO. 

- OxGOCO 


BiLs 0 through 5 of the low-order byte indicate, for visual 
media types, the pixel depths at which the track cun be displayed. 
If bit n Ls set to 1, then ilie track cun be displayed at pixel depth 2^^ 
Tlius, tliese 6 hiLs can indicate pixel depdis from 1-bit (that is, 2^) 
to 32-bil (2^), More dian one bit can \’>e set, inriicaiing that the muh 
am lie displayed at multiple pixel depths. 
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The Movie Toolbox provides two funetions, GetMediaQuality 
and SetMediaQuailty, which we can use to gel and set a media's 
quality value. Here’s an example of setting a video track's quality 
to display at 16- and 32“hit pLxel depilis, at die highest quality; 

short myQusUty = medlaQuaiity.Best + 32 + 16: 
SetMediaQuality [jnyMedia. myQuality) ; 

If two or more tracks could be selected from a given alternate 
group (that is, their languages are the .same and they are both 
valid at the current bit depth), QuickTime selects the track with 
the highest relative quality. 

Creating Alternate Groups 

Suppose now that weVe assigned appropriare languages and 
quality values to some of the tracks in a inovie. At this point, we 
can group these tracks into alternate track groups by calling 
SetTrackAlternate, which is declared essentially like this: 

void SetTrackAlternate (Track theTrack, Track alternateT): 

Hie first parameter, theTrack, is die track we want to add to a track 
group. The second parameter, alternateT, is a track that is already 
in that group. If theTrack Is not already in a group and alternateT 
is in a group, then theTrack is added to the group that contaias 
alternateT. If theTrack is already in a group but alternateT is not, 
then alternateT Ls added to the group dial contains theTrack. If 
b(3th theTrack and alternateT are already in groups, then the two 
groups are combined into one group, If iieitlier theTrack nor 
alternateT is in a group, then a new group is created to hold them 
both. Finally, if alternateT is NULL, then theTrack is reiiioved from 
the group that contains it. 

In praaice, this is actually much ea.ster than it may sound 
from that description. For instance, if myTrackt and myTrack2 are 
tw'o video tracks with dilfereni media langtiages, w'e can group 
them into an alternate track group like this: 

SetTrackAlternatefjnyTrflckl, tnyTrack^l : 

.And we can remcjve myTrackI from iLs group like this: 
SetTrackAltsrnateCmyXrackl, NULL)i 

If we want to find all tracks in a particidar alternate track 
group, we can use the GetTrackA Item ate function, which is 
declared like this: 

Track GetTrackAlternatG [Track theTrack): 

GetTrackAlternate returns the tJMck identifier of the next track 
in the alternate track group. For iasiance, 
GetTrackAlternate(myTrackl) would return myTrack2, and 
GetTrackAlternate(myTrack2) would return myTrackI. As you can 
see, ailling GetTrackAlternate re|3eatedly will eventually return the 
track identifier w'e started with. And if tliere is only cjne track in 
an alternate track group, GetTrackAlternate will return tlie track 
identifier we pass it. 


Getting and Setting a Movie’s language 

Recall that, when a movie file Ls first opened and prepared 
for playback, QuickTime selects the alternate track whose 
language code matches that of the current operating system. Wg 
can dynamically modify the language used by a movie by calling 
tlte SetMovieLanguage function. For instance, we can execute this 
code tf) set the language to French: 

SetMovieLanguage CroyMovie, (long) langFrench); 

QuickTime inspects all alternate track groups in the movie and 
enables the track in each group tliai ha.s that language. If no track 
in any alternate group has the specified language code, then the 
movie’s language is not changed. 

Interestingly, QuickTime does not provide a 
GetMovieLanguage function, even thcnigh it might sfjmelimes be 
useful for us to know^ the current language being used in a movie. 
We CTin define our own function, however, to get this information. 
Listing 3 derme.s tlie QTUtils_GetMovieLanguage function, which 
looks at each enal>led track and inspects the language of that 
track’s media. 

Listing 3: Finding a movie’s current language 

Qll iiils_GerMo>id.a[iguagc 

short QTUtllE_GetMovleLanguage (Movie theMovie) 

I 

Track tiyTrack - HULL; 

Media tnyMedia - NULL: 

short tnyTrsckCount* Tnylnde^:: 

short my Language = 1: an invalid btiguagc c(xlc 

myTrackCouni = GetMovieTrackCount(theHovia): 
for (raylodex “ 1; iriylndex <“ myTrackCount t myludex’H’) { 
myTrack = GetMovieludTrackCtheMovie! t my Index] : 

If [[myTrack NULL) && GetTrackEnabled[myTrack]) f 
Track myAltTrack = NULL: 

myAltTrack GetTrackAlternate(myTrack): 

If ((niyAltTrack 1= NULL) (myAltTrack 1= myTrack)) f 
myMedla “ GetTrackMedia(TnyTrackl : 
myLatiguage = GetMediaLanguage [niyHedifl) : 
break: 

I 

I 

) 

return (myLanguage): 


You'll notice thiii we don’t simply get tlie language of tlie first 
enabled trat:k’s media; rather, we call GetTrackAlternate to make 
sure (hat the track is contained in an alternate track group tliat 
contains at least two tracks. (A media's language is ignored by the 
Mfwie Tnollxix if the eorresponding track is not part of any 
alternate track group.) 

Listing 4 shows the QTAIt_HandleCustomButtonClick function, 
which W'e use to handle user dicks on the custom button in the 
controller liar. WeVe encountered code like this liefore, .so we ll 
he content here to just show the c(Kle. 

Listing 4; Handliag clicks on the custoni controUer bar 

button _ 

QTAlLHaiidteCustomfluaoiiClick 

void QTAlt_HandleCustoniButtOTiCllck (MovieGontroller thcMC, 
EventRecord ‘tbeEvent, long theRefCon) 
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goes down is the one who gets the page, 

68k, PPC and Carbon 

Web based ac/m/n/s/ra/ion /efs you check on and resforf 
your servers from anywhere. 

Customize your response to an outage with Apple Scnpf. 


email us at whisfleblower@sentman.coin 
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REALBASiC SHOWCASE 



Picture 

Play 


Create digital image compositions on 
your Mac, quickly and easily. 



For more information, 
email chris@crescendosw.com, or 

visit us today at www.c re scendosw.com ! 


Corona 



accounting software 



"Easy to set up, easy to use, 
and excellent support from 
the developer." 

Five stars on Vei-sionTracker coTn 
Four cows on Tiicows.com 


• cash entry 
• invoicing 

• payroll 

• reports 


$64.95 


Version 1,9 now with: s$le& tajt accounting 
“keyless entry" invoices 
drag 'n drop accounts 


Free 30-day trial 

http://homepage.mac.com/idle\%ild/CoronaUS.hqx 



A best friend for business! 

p.o. box 472 • aurora • Oregon • 97002 
idlewiid^mac rCom 





iScreensaver 


designer 


for Macintosh and Windows 



the world's only cross-platform 
screensaver design tool 


• build both Macintosh and Windows screensavers 
With a singie dick, on whatever system’ you are using/ 

• use any QuickTime movie format : 

Macromedia Flash, MPEG, Cinepak, MP3, Midi, AVI, DV Video... 

* include a hidden movie that can be unlocked 
with a registration code 

• customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

• screensavers install without DLLs, extensions, or restarts 


simple 

WYSIWYG 

editor 

supports 
interactive Flash 
and QL;/ck:77me 

consistent 
cross-piatform 
user interface 

try before you buy 
fuUy functional 
oniine downloads 





3. - V- ■■■■ 




the fScreerrscrv^r edrtmq emwonmenr 


http :/iScreensa ver. net 

email : Info @ iScreensaver.net 


* supported systems, as of November 2001, Indudei 
i^clntosh OS 0,6 to 9.2, Microsoft Windows 9S/9SyME, frr4/NT2D00/XP 
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REALBA5IC SHOWCASE 



LIGHTHOUSE 


theitime-Saving 
Internet Assistant 


Spending long tiours online searching for code snippets 
and developer documentation? Maximize your online time 
with Lighthouse, the perfect Internet companion for software 
developers, web designers, and anyone who utilizes the Web for 
research. Its small, compact interface fits nicely in the corner 
of your desktop, freeing up valuable soreen space for your daily 
work applications and web browser. 


tlEUp-l 

m 





Bf^I 


5i! 

' ' =» 


Lighthouse Standard Edition is now available as freeware for 
Classic Mac, Mac OS X, and Microsoft Windows. 

Unlock the extra Platinum features for 
only $10 us [with free upgrades). 


@ 


El 

□ 


Searcli the Web with free pfugins 
or create your own search plugins 

Store Account Info for access 
to membership sites & web mail 

Piugitis Manager to add / edit 
Lighthouse plugins 

Web Favorites Organizer offers 
advanced bookmarking features 

Note Keeper saves code snippets, 
ideas, research notes, etc. 

Local Weather at your fingertips 
for home or travel 

Calendar & World Clock 

Quick reference tools 


STAfIDARO 

EDiTtON 

sr 

□ 

□ 

□ 

□ 


PLATINUM 

EDITION 

a*- 

S’ 

0- 

0 

0 

0 

sr 


STIMULUS 


Image Viewer and 
Multimedia Player 


Enjoy your personal collection of photos, digital music, 
video clips, and more wlHi one integrated browser! 

Download the full-featured trial version for either Classic Mac 
or Mac OS X, Stimulus is only $12 us (with free upgrades), 


' Supports 18 popular 
file formats 

’ Plays Audio CD tracks 
& iPod audio files 

' Multimedia Slideshow 
(perfect for playing MP3 
files & viewing photos) 

Zoom In/Out 
■ Scale-to-Fit option 
File Properties 

Easy-to-use interface 


eee 

beb 


Stimulus 


► & Docuirwtn* 

▼ (5? My EJownfcmcf* 

tjj likittebo^rd.mav 

B9 iLirflng.|cHi 

¥ B MyM%iJtt 

4'ii Shwii mpj 
4''i t^rum tunp.urjv 
’f My St uff 

L& Vrdia.ntpii 
H Photo Sho«t,iif 
tj Tfmci^uirv.airi 
H uftlmati.pnft 
H LogoDeiign p^d 



ectric: 





DOWNLOADS 

Utter ;f ll^^nttpti^Www.ebutterfly.com 



fOontrol up to 12 changers (4,800 music CDs) 
^ Control Any Brand Stereo Receiver 
Play MP3 and other Sound Files 
" - Plus much, much more!!! 


wwvir4titletrack.com info@titletrack.com 


ftp> get pxFTP 


The power and stability of 
the command line... 

The ease of drag and drop! 

pxFTP 


Get it today at... 

PIDOG.COM 


From the maker of... 

piDock 


ft 

^TelnetLauncher 

piDog Software 
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HenuHaiidle myMenii “ NULL; 

WindowObject oiyWiiidowObject = 

(WindowObject)theRefCon; 

AppllcationDataHdl inyAppData = NULL: 

StringPtt loyMentiTitle “ 

QTUtils_ConvertCToPascalStrldg(kMenuTitle); 
tllntlfi myCount - 0; 

// nuke sure wc got parameters 

if ((theMG = NULL.) | | {theEvent -- NULL} || 

(theRefCon = NULL)) 
goto bail: 

myAppData “ (ApplicatlonDataHdl) 

QTFrame^GetAppDataFroinWlddowOb j ect (myWiTiidowOh j ect); 
if (rayAppData ^ NULL) 
goto bail: 

// create a new menu 

myMenu NevMenu(kCiistoniButtonMenuTD» rayMenuTitle); 
if [jayMenu ]“ NULL) | 

long myltejn = 0; 

Point myPoint; 

// add all track languages in the CLirrent movie to the pop-up menu 
myCount = QTAIt_AddHovieLan£uageBToMenu [myWindowObjecit, 
rayMenu): 

if {((/"niyAppData} .fCurrMovioIndex > 0) hk 

((^‘myAppData) pfCurrHovielndex <= rayCaunt)} 

MacGbockMenuItem(myMenu. (*‘myAppOata),fCurrHovielndex+ 
true): 

// inserT the menu Lnto the menu list 
MacInsertHenufmyMenu, bierHenu): 

// find the location of the mouse cJlck; 

// tile top-left corner of the pop-up menu is anchored at tliis point 
myPoint = theEvent->wbere: 

LocalToGlobai(^myPoint); 

// display the ptip-up menu and handle the item selected 
myItem = PopUpMenuSelect(myMenUH myPoint^v* myPoint^h. 
myltem); 

if (myltera > 0) f 

(**myAppData)^fCurrMovielndex - myrtem; 

SetMovieLanguage(MCGetMovie(theKC). 

QTAl t_Ge t Language Co deForMenulteinlTid ex (myWlndowOb jec t + 
myltem)): 

UpdateKovie(MCGetMovieftheMC)): 

1 

// remove the menu from Uie nicnu list 
MacDeleteMenuCGetMenulD(myMenu)): 

// dispose of the menu 
DisposeMenu(myKenu): 

1 

bail: 

free(rayHenuTitle3 : 

] 

We've already seen aE of the application-defined functions 
used here, except for QTAIt_AddMovieLanguagesToMenu. listing 5 
shows our definition of this function. 

Listing 5; Adding languages to the pop-up men u 

QTAlLAddMovieLtnguagesToMenu 

static Ulntlb QTAlt_AdtiHovieLanguagesToMenu (WindowObject 
tbeWindowObJect, MenuHandle theMenu) 

[ 

AppllcationDataHdl myAppData ~ NULL: 

Movie myHovie = NULL; 

Track myTraek = NULL: 

Media myHedia = NULL: 

short myindex; 

Ulntl6 myCount - 0: 


myAppUata = (ApplicatlonDataHdl) 

QTFraniG_GetAppDataErDmWindowObj ect (tbeWindowOb ject); 
if (myAppData = NULL) 
goto hail: 

// update the mask of movie languages 

QTAlt_Updat eMovieLangua geMask(theWlndowObj ect): 

// add menu items 

for (royindex = 0: tnyindex < kNumLanguages: mylndex+t) f 
if {(* *EayAppDaLa) .fLanguageMask[myIndex] I) f 

StrlngPtr mylteinText = 

QTUtils_ConviertCToPasca] String{gLangtiageArray[mylndex]); 

MacAppendMenuCtbeMenu. myltemText): 

free(mylteinText): 

aiyCount++; 

I 

I 

bail: 

return(myCount): 

I 

Enabling and Disabling Alternate Track Selection 

The selection of alternate tracks based on the media 
language and quality occurs automatically w4ien a movie file is 
first opened. We can override this default behavior, however, by 
passing the newMovieDontAutoAlternates flag when we call 
NewMovieFromFile or NewMovieFromDataRef (or any of the other 
NewMovieFrom calls). Similarly, we can change the state of auto 
alternating dynamically using the SetAutoTrackAlte mates Enabled 
function. For instance, we can turn off auto-aliernating for a 
specific movie like this: 

SetAutoTrackAlternatesEnabledtmyMovie. false): 

When auto-alternating is on, the Movie Toolbox rescan.s 
alternate track groups whenever we execute a function that 
might change one of the relevant selection criteria. For instance, 
if we change the movie's language (by calling 
SetMovieLanguage), the Movie Toolbc^x rescans all alternate track 
gnmps to make sure that the correct alternate track is enabled. 
Likewise, the Movie Toolbox performs this check if we change 
any of the relevant visual characteristics of the movie (by calling 
functions like SetMovieGWorld, UpdateMovie, or SetMovieMatrix). 
Moreover, the alternate track groups are rescanned if the user 
performs any action that causes QuickTime to call any of tiiese 
functions internally, such as moving tfie movie window from 
one monitor to another (since the monitors may be set to 
different pixel depths). 

If for some reason we want to explicitly force die Movie 
Toolbox to rescan die alternate groups in a file immediately, we 
can call the SelectMovieAlternates function, like so: 

SelectMovleAltemates(myMovie) : 

Note, however, that if all tlie tracks in a particular alternate track 
group are disabled when we call SelectMovieAltemates, then 
none of the tracks in diat group will be enabled. 
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changing Alternate Tracks with Wired Actions 

QuickTime provides a wired action, kActionMovieSatLanguage, 
which we can use in wired attms to change a movie's language. 
This action takes a single parameter, which is a long integer tJial 
specifies the desired language. The function 
WiredUtils_AddMovieSetLanguage, defined in Listing 6, shows how 
we can add these wired actioas to an atom container. 


Listing 6: Adding a set-language action_ _ 

Wi red U tiLvAddMovi t SctLmgujgi: 

OSE r r Wir edU tils_AddMo vieS etLangaa ge 

(QTAtoraCoritainer' theContwiner, QTAtora theAtom* 
l&ng theEvetit, long theLanguage) 

( 

QTAtom rnyAciionAton] = 0: 

OSErr myErr noErr; 

rayErr = WiredUtils_AddQTEventAndActionAtoins(tlieContaiTier, 
tKeAtom. theEventp kActionMovieSetLsTTguage, 
imyActlonAtoiD) : 

if (royEri: != noErr) 
goto bail; 

theLanguags ^ EndianS32_NtoB(theLaiignage}; 

myEri: ” WiredUtils_AddActionPa3:aineTerAloffl (tb^Container, 
myActionAtQTn, kFlrstParam. slzeof(theLanguage), 
itheLanguago. NULL): 


bail: 

return (tnyErr); 

I 


There is currently no wired action Ibr setting a media’s 
quality, and tlicrc are no wired operands for getting a movie’s 
current language or quality. Sigh. 

Alternate Movies 

Let’s turn now to consider alternaie movies and alternate 
reference movie.s. An alternate reference movie file is a movie 
file that contains references to a set of allernate movies, together 
widi the infonnation that QuickTime should use to select one of 
thtjse movies when the alternate reference movie file is opened. 
This information can rely on a wide range (jf features of the 
operating environment, including: 

• Internet connecticjn speed, 

• Language of the operating system software. 

• CPLf speed; this is a relative ranking, ranging from 1 
(slowest) to ^ (fastest). 

• Installed version f>f QuickTime. 

• Installcxl version of a specific software component, 

• Netwt^rk connection status. 

To create an alternate reference movie, we need to know 
which alternate movies it should refer to and what criteria are to 
be used in selecting a movie from among tliat collection of 
alternate movies. Apple provides a utility’ called MakeRelMovie 
that is widely vised for creating alternate reference movies. 
Figure 5 shows the MakeRefMovie main window, containing 
several panes that de.scribe the alternate movies and their 
selection criteria. 



Figure S: ^fhe main window of MakeRefMotie 


Each pane specifies either a local movie file or a LTRL to a 
movie file, together widi the selection settings for that movie. 
Notice that each pane also contains a check liox labeled ""Flatten 
into output” (see Figure 6). If this b(3x is checked, then the data 
for the specified movie will he included iu toia in the alternate 
reference movie file. This movie (let’,s call it the contained 
movie) will be selected if the alternate reference movie file is 
opened under a version of QuickTime prior to 3 (which is the 
earliest version that supports alrernare reference movies) or if 
none of the criteria for .selecting one of the other alternate 
movies is met. Clearly, at most one alternate movie should be 
specified as the contained movie, and MakeRefMovie enforces 
this restriction by allowing at most one of these boxes to be 
checked at any one time. 


L nciittfiB: It uwv 

Datii flale: 

SIZK 9I.&4KB 


I Netwprfc StatHt | 



1 Za.S/33.6 Modem 


CPDitv: 

S 1 

I’rfority; 

1 tttiffirrffffiif 

*) 

BylPt prr vpiuriili| 

1 

iangiiage: 

1 SitMpm-ff/si/ 

*) 

Udritan:! 

*1 

CPU 

1 


0 Flatten Info output 




figure 6: An alteniate movie pane 

ITiere are also other tools available for creating alternate 
reference movies. If you like lo work with XiMl, you can use the 
XMLtoRefMovie utiliry written by fomier QuickTime engineer 
Peter Ihxldie. XMLtoRef'Movie converts a text file containing an 
XML-based description of alternate movies and selection criteria 
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The Key is in Your Hands! 


Does your dongle do all this? 


Software Goes Online 

Electronic Software Distribution - safely protected by WIBU-KEY. 

Web Remote Programming 

Reprogram the WiBU-BOX hardware at the customer’s site directly 
via the Internet. 


IVeb Authentication 

Secure authentication via a two-way-encryption. 

Pay-Per-Use 

Usage dependent accounting. 


MacOS9&X 

WIBU-KEY supports Mac OS, Windows and heterogeneous networks. 

> Yes? Then you are already using WIBU-KEY! 




► 


No? Then order your Test Kit 

at 1-800-986-6578 


You will find more information at 

www.griftech.com 


.eCRlFFlN 

TECHNOLOGIES 


USA. Canada: Grrlfiin Technologies. LLC 
phone: (785) 832-2070 fax: £7BS) 832-8787 
email: sales@griftech.com www,griftech.com 


r 


UIBU 

SYSTEMS 


WIBU-SYSTEMS AG 
76137 Karlsruhe, Germany 
WIBU-SYSTEWS USA< Inc 
Seattle, WA 93101 
email: |nfo@wibu.coiTi 


www.wibu.com 


Test Kits also available at: 

A/gentirta Ipfotfsafield-group.com, Au^ralia sirnone.eckerietfwJbu-tom, Belgium wibuBimpakt ber Croatia ariesfiarfe^lir, Denmark ivhaSdanbit.rfk. 
Finland finebyteOfinebyte.com, Franca rnfofineol.fr, Hungary mfo@nnrsott.hu, iaisin info@suncarla.co.Jp, Jordan, Lebanon starsoft@cyberla.net. lb, 
Korea dhklmm@wlbLJ.c0.kr, Luxembourg WibUQirrpakt.be, Netherlands. uvibuQrrTipdkt.l>e,^rtugal dubrtQdubit: pt, Syria starsoftSiiyberia.net. lb. 
Thailand pfeechaddptf’th.com.iJnjted Kingdom infoOco^eworkxom, USA sales@griftech.com 

















into an alt^^mate reference movie file. Listing 7 shows the XML 
data for the information shown in Figure 5. 

listing 7: Specifying an alternate reference movie using 
XML _ 

pitch_rcf xml 

<q_t ref movie) 

(refmovie sj:c”"flrst_pltch_56 .mov" data-rate=''56k modeiii” /) 
<refinDvie stc=^"first_pltcli_tl .mov*" data-cate="tl'' /> 
(/qtrefmovie) 

And Listing 8 shows the XML dam for an alternate reference 
movie that has a contained mtwie (or default moviey in 
XMLtoRefMovie parlance). 

Listing 8; Including a c ontai ned movie using MIL _ 

pitch_icf.xml 

<qtrefmovie) 

<default-movie src“"file:///MedltationE/pitch.iHov" /> 
<reflnovie ei:C”"first_pltcb_56,lDC}v'‘ data'rate=''5bk modeni'* /> 
<reftnovle src='’firfit_plteh_tl .mov" data-rat&=''tl" /> 
</qtrefmovle> 

In the rest of this section, HI assume that we already know 
which set of movies to use as alternate movies and what the 
selection criteria are. We want to see how to take that 
information and create a final alternate reference movie file. 

Creating Alternate Reference Movies 

WeVe learned in earlier articles that a QuickTime movie file 
is structured as a series o{ atoms, Eacli atom contains some data 
prefixed by a header. The header is 8 bytes long and specifies 
the length of the entire atom (Iteader included) and the type of 
the atom. All of this data (header and atom data) is stored in l)ig- 
endian format. 

A typical QuickTime movie Rle contains a movie atom (of 
type MovieAlD, or 'rnoovT, wliich contains a movie header atom 
(of type 'mvhd') and one or more track atoms (of type Irak"). A 
self-contained movie file also contains a movie data atom (of 
type mdat'). Figure? illustrates this structure. 



X 

r 

iilom stabs 


abwmdata 

h 

atom ttata 

moDV 

iwvhd 

trak 

mdat: 



figure 7: The stmcture of a stmulard QuickTime moiieftie 


I'he movie atom contains the movie header atom and the track 
atom, so its total length is the lengths of thcxse atoms plus the 
length of the movie atom header (that is, x + y + 8), 

An alternate reference movie file Likewise contains a movie 
atom, ))ut it dtjes not always contain a movie header atom or any 
track atoms. Instead, when tliere is no contained movie, the 
movie atom contains a single reference mome record atom (of 
type ReferenceMovieRecordAID, or rmra‘); in turn, this reference 
movie record atom contains one reference movie descfiptor atom 
(of type TmdaO for each alternate movie descrilxrd by the 
alternate reference movie. Figure 8 shows this general stmcture. 



M 

J' 

M 

aii3in<iata 

m 



■DOV 


rwla 

mda 

atofti data 


Figure 8: Ihe structure of an alternate reference mome file 


When an alternate reference movie file does have a 
contained movie, the movie header atom and the track atoms 
should follow tlie reference movie record atom, as shown in 

Figure 9- 




X 

y 


M 

atomiJsUa 

IV 



noDv 


■ivhd 

-trak 




Figure 9: An alternate reference movie 
fide uitb a contained movie. 


A reference movie descriptor atom describes a single 
alternate movie. It contains other atoms that indicate the 
selection aiteria for that alternate movie, as well as a data 
reference atom that specifies the ItKalion of the alternate movie. 
I'he header file MoviesFormat.h contains a set of atom ID 
ctjnstants that we can use to indicate tiiese atom types: 

mm t 

Refe renceHovifiReco rdAlD 
FOUR_CHAR„CODE( *rmra0H 

ReferenceMovieTescriptoji AID 
FOtm^CHAR_GODE( ^ rradaD * 

ReferenceMovieDataR 0 fAID 
RsferenceMovieVersionCheckAlD 
FOUH_CaAR_CODE(’ nnvc'), 

Re f ereticeMovieDa taRat eAID 
FOUR_CHAR_CODE(■rradrD» 

Refereuc eHovle Compon entCb e c kAID 
RefereaceMovieQualltyAID 
ReferenceMovleLanguagaAlD 
F01FR_CHAR_C0DE (’ rmla *), 

Re f e r e nc eMo vi e CPU Ra 11 n g AID 
Re f e r enceMovieAlt e mat ©Group AID 
ReferenceHovieMetworkStattisAlD 
FOUK_CIlAR_CODEDrtiet*) 

): 


Specifying an Alternate Movie 

A reference movie descriptor atom must contain a single 
data reference atom, which specifies an alternate tnovie. The 
atom data for the data reference atom Ls a reference motie data 
ivference record, which has this structure: 

struct ReferenceMovleDutaRefRecord I 
long flags; 

OSType dataRefType; 

long dataRefSlzc: 

char dataReffl]: 

I: 


Currently, tliis value is defined for the flags field: 

enum I 

kDataRefIsSelfContalned ° (1 << 0) 

I; 


= FOIIR_CHAS_GODE {* td tf'). 


= F0UR_CHAR_C0DE(’toed *). 
= FOUR_CHAR_CODE (‘ rniqu ’). 


= FOUR_CHAR_CODE{•rmes’). 
- FOUR_CHAR_CODE(‘rraag’). 
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1), strlenU'*royAppData) *fURL) + 1} i 


If the flags field is kDataRefIsSelfContained, ilien the other fields 
^ire ignored and QuickTime searches for the mD%ie dam in the 
alternate reference movie itself (as shown in Figure 9>. 
Otherwise, if the flags field is 0, QuickTime uses tlie data 
reference ccmtained in the dataRef field, using the dataRefType 
and dataRefSize fields to determine the type and size of that data 
reference. 

The dataRef field can contain any kind of data reference 
supported by QuickTime, but usually it’s either a file data 
reference or a URL data reference, (See “Somewhere I’ll Find 
You” in MacTech, October 2000 for more information about data 
references,) Listing 9 shows some code that builds a data 
reference atom, based on information stored in an application 
data structure associated with a pane. 


listing 9: Creating a data reference atom 

M RM _Savt:Rcft:RUCcMfivic 

ReferEnc^ovieDetaRefRecord inyDataRefREc; 

AliasHandle myAllas = NULL: 

Ptr rayData ^ NULL; 

Igng myFlags; 

switch{(* *iiiyAppData), fPaneType) I 
caEE kMRM_MoviEPaneType: 

// create an alias record for the movie 
myErr = NewAllasC&gRefMovieSpec, 

&C*'niyWindowObjact) ,fFileFSSpec, &myAlias): 
if £myErr !“ noErr) 
goto bailLoop: 

if (C* *tiiyAppData) .f Cur rant Flat ™ kMRH_FIatCheckOn) 
myFlags ^ kOataRefIsSelfContainad; 
else 

myFlags “ 0: 

myDataRefRec . flags ^ EjidiatiU32_NtoB [myFlags] : 
myDataKefRec.dataRefType “ 

EudianUa 2_Nt dB( kHRH_DataRefTypeAiias): 
myDataRefRec.dataRefSize = 

EndlanU32_NtoH(GetHandUSl2e{ (Handle) myAlias)); 

// alloaitc a data bltM:k :ind copy the tLitii retrrcncc record and aJiits rectjrd into it 
myData = NewPtrClearCcizeaf(ReferenceHovieDataRefRecord) 

+ GetHandleSize((Handle)royAllaa) - 1); 
if {ntyData = NULL) 
goto bailLoop: 

HLock((Handle)myAlias}: 

BlockJioveC&myDataRefRec, myData. 

sizeofCRefereiiceHovieDataRefRecord) - sizeof{char) - 
Ui 

BlockMove(*myAlias , (Ftr) (layData + 

sizeof[ReferenceHovioDataRefRecord) * sizeoftchar) - 
1), GetHandleSize((Handle)myAlias)); 

HUnlock((Handle)inyAlias) t 
break: 

case kHRM_iJRL Pan eTyp e: 

myOataRefRec,flags ^ EndianU32_NtoB(DLJ: 
myBa t aR e fRec,d a t aRe fType “ 

EndiaiiU32_NtoB (kMRM_DataRefTypeURL); 
rayDataRefEec.dataRefSize = 

BndianU32_NtoB(strlen({*'rayAppData}.fURL) + 1): 

// alkxutf a iluta block jnd copy the ihia reference rectynd and URL into it 
myData ” NewPtrClearlsizeof (ReferenceMovieDataRefRecord) 

+ sttlen( (''myAppData),ftIRL) ' 1): 

If (myData = NOLL) 
goto hailLoop; 

BlockHDve(&TnyDataRefRee, myData. 

slzEof(ReferenceMovieDataRefRecoed) ' slzeof(char) - 

1 ): 

BlockMovet(**myAppData),fURL. (Ptr)(myData + 

slzeof(ReferenceMovieDataRefRecord) - sizeofCchar) - 


break: 

} 


Keep in mind that the Reference MovleData Ref Record structure 
contains as its final field a single character, which is a placeholder 
for the actual data reference; this means that we generally need to 
subtract stzeof(char) from sizeof(ReferenceMovieDataRefRecord) to 
get the “real" size of the record. 


Specifying Selection Criteria 

A reference movie descriptor atom can contain one or more 
atoms that indicate the selection criteria for the movie specified 
in the data reference atom, lb indicate that that movie should be 
selected based on the user’s Internet connection speed, we add 
a ciaia rate atom, of type ReferenceMovieDataRateAlD. The atom 
data for the data rate atom is an alternate data rate record, 
wliicli lias tliis stnicturc: 

siruct QTAltDataRateRecord I 
logg flags: 

long dataRate: 


The flags field is cunrendy always 0, and die dataRate field 
should contain one of these constants: 


enum I 

kDataRatel A4l1od emRat E 
kDat aRa t e 2 8 8Mo d emRa t e 
kDataRatElSDNRate 
kDa taRateDuaiJ SDN Rat e 
kDataRatE256kbpsRate 
kDat aRat e384kbpsRate 
kDataRateS12kbpsRat e 
kDataRate7 68kbpsRat e 
kDataRateiMbpsRatE 
kDataRateTlRate 
kDataRateInfiniteRate 
I; 


- UDOL. 

- 2800L. 

= 5600L, 

= 11200L. 

= 25600L. 

- 38400L. 

= 51200L. 

- 7e8Q0L. 

- lOOOOOL, 

- ISOOOOL* 

= 0k7FFFFFFF 


Figure 10 shows die atom data of a reference movie 
descriptor atom for a movie that is appropriate for downloading 
across a connection whose speed Ls 56 Kb/sec. 


rdrf 


atom data 


y 

0 

rmdr 

5600 


Figure 10: A conneclion speed reference movie {descriptor atom. 


When an alternate reference movie is opened, QuickTime 
looks for a reference movie descriptor atom w^hose data rate 
atom matclies the connection speed specified in the Connection 
.Speed pane of the QuickTime control panel. If no data rate atom 
e,xactly matches tiiat speed preference, dien tlie movie with the 
higliest duui rate that is less than ihat preference will be selected. 
If, furtiier, no data rate atom specifies a data rate that is less than 
the user’s preference, then the alternate movie with the lowest 
data rate will be selected. 

Tt> indicate that an alternate movie should be selected 
ba.sed on the o|>eraljng system’s language, we add a langimge 
atom (of type ReferencGMovieLanguageAlD) to the reference 
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struct QTAltLanguageRecord [ 
long flags: 

short language; 

J : 

The flags field is once again always 0, and the language field 
should contain a language code. Listing 10 shows a chunk of code 
tli^tt creates a language atom. 

IJstkig IOl Addifig_a J^.gua£e _a^ 

MRM_SavcRt!fcfc:ncL-JV|oviL‘ 

if ((**myAppData).fCurrLanglndex > 0) I 
QTAltLan guageRec ord myLanguageRec: 

long myAtoniHeader [2] ; 

myLanguageRec.flags ^ OL; 
itiyLanguageRec . language = EndianS16„NtoB( 

(* *myAppData) . fCurirLang}; 

// concatenate the header for the kingiiage atom 
myAtomHeader[0] - EndianU32_NtoB( 

(myLanguageRec) + myAtoniHeaderSize) : 
myAtoinHeader [ 1] = Etidiatili32_NtoB ( 

RaferenceMovieLanguageAID); 
myErr = PtrAndHandimyAtoroHeader, rayRefUavieDescAton?, 
myAtomHeadarSiKe): 
if (myErr 1= DoErrJ 
goto bail: 

// concatenate the language data onto ilie end ot the reference movie descriptor 
atom 

myErr = FtrAndHand(SiiiyLanguageRec. myRefMovieDEscAtam. 

sizeof (jnyLanguageRec)) : 

If (myErr 3= noErr) 
goto bail: 


Suppose we have created an altermte reference movie atom 
stRicture in memory, which lias the structure .shown in Figure 8. 
Supp<xse also that we have opened the movie iliat is to be flattened 
into the alteniate reference movie file. We'll begin by creating a file 
that is the size of the reference movie record atom tliafs contained 
in the existing alternate reference movie atom; 

myErr = ESpGreate(^gRefMovieSpec, F0UR_CHAR_C0DE(*TV0D‘. 
HovieFileType, 0]; 

myErr = ESpOpenDEf^gRefMovieSpec, fsRdUrPerm, ^myRefUmn): 
myMovAtomSize - GetHandleSize(thEMovleAtom): 
myRofAtomSize = myMovAtomSize - myAtomHeaderSize: 

* (long *)]nyData = EndianU32_Ntol (ziyRefAtomSize) : 

‘(long *1(myData f sizeof{long)) = 
EndianU32„HtoB(FreeAtomType): 

SetFPos {inyRefNunt. f sFromStart. 0); 

FSWriteimyRafNum. ^myConnt, myBata): 

As you can see, this new file contains all zeros, except for die 
8-byte atom header; the atom type is set to FreeAtomType (Uiai is, 
free'). Figure 12 shows the new file at this point. 


jr 

free 


Figure 12: Step /, Space for ibe n^erence nmme record atom 


To indicate that an alternate movie should he selected based 
on the movie quality, we can add an atom of’ type 
ReferenceMovieQuatityAJD to the reference movie descriptor atom. 
In diis case, the atom data is simply a signed long integer, as 
shown in Figure 11. 


jr 


rdrf 


atom data 


y 

onqu 


11 


Figure 11: A quaiiiy reference mouie dcsctiptor atom 


If two alternate movies meet all other listed selection cnteria, then 
QuickTime uses the quality atom to break the tie; tlie ailernaie 
movie with the higher specified quality is selected. 

Adding a Contained Movie 

It's relatively straightforward to build an alternale reference 
movie file if there is no containeri movie; as weVe .seen, we simply 
need to add the appiopriate atoms lo the movie file (and w^eVe 
had plenty of practice doing that in earlier articles), Things gel a bit 
more complicated when we want to bitild an alternate reference 
movie file that holds a contained movie, since we need to merge 
the contained movie wiih the alternate movie data to obtain the 
file shown in Figure 9 This actually isn't al! that complicated, 
thanks to the fact that tlie FlattenMovieOata function will happily 
append the flattened data to an existing movie file, if we tell it to 
do so. Let's see how to exploit that capability to create an alternate 
reference movie file witli a contained movie. 


Now we ll call FlattenMovieData to append tlie data for the 
contained movie onto the entl of this file; 

piyMovie = FlattenMovlsData (thet^ovie, 

flattenAddMovieToDataFork | 
flattenFotceMovleResourceleforeMavieDatu. 
igRefMovieSpGc. 

F0UR_CHAR^G0DE('TVOD'), 
smSystemSert pt, 

OL) : 

Notice dial we pass the flag llattenAddMovieToDataFork to append 
the data to tlie existing file and 
flatten Force Movie Resource Before Movie Data to ensure that the 
movie atom is written out at the beginning of the data. At this 
point, die Hie lias the suiicture .showai in Figure 13. 


Figure / jt* Step 2: 7 be flattened data of the contained movie 


We reopen the file and read die size of die moov’ atom; 

tnyErt = FSpOpenDF (fijgRefMovleSpEC , fsRdWrPet'in. ^imyRefNutn): 

SetFFos (TDyRefNuni, f sProinStart, rDyRefAtomSize) : 

TDyCount 3: 

myErr = FSRead(inyRefNum. 6fmyCount. &{myAtom[0])): 
myAtomtO] = EndLanU32_BtoN(rayAtoni [0]) ; 


Now w^e know^ \vhat the size of the entine movie file should l:>e, and 
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we allocate a block of memory large enougli to hold the file clata^ 

myData = NewPtrClear (myRefAtomSize + iiyAtQin[0]); 

We write a 'moov’ atom header into this new blcK'k of data: 

"^(long *)myData = EndiaTiU32_HtoB(myRefAtoraSiza + inyAtoiii[0]); 
'(long •)(myData + siseof(long)) = ETidianU32_NtoB(MovieAlD) ; 


[ 

inyErr = FSpOpenDF (£igRefMovieSpec , fsRdWrPerDit &myRefNum); 
if (layErr ^= noErr) 
goto bail: 

myMovAtoniSize = GetHandlaSize [theMovieAtom) ; 
myRafAtomSise = royHovAtomSize ■ myAtomHeaderSiza: 

HLock (theHoviaAtott]) : 


llien we copy the reference movie record atom into place: 

BlockMoveData(‘theMovieAtotD + luyAtomHeaderSize t myData + 
myAtoniHeaderSize, myRefAtomSize) : 


And then we read the flattened movie data out of our existing 
movie file into tlie appropriate spot in our block of data: 

uiyConnt " myAtom [0] ‘ myAtomHeaderSize; 

inyErr = FSRead(iJiyRefNum, fiittiyCount< myData yAtoniHeaderSize + 
ToyRefAtotriSiza}: 


We’re almtJSL done; the block of memory now looks like 

Figure 14. 


F 

mlTA 


atoTFidsfea 


mvlKl 


alom ctatei 


H 

trak 


Figure 14: Stef) 3: ihe motie data in memor}> 


Ail we need to do now is w rite this l^lock of data hack into the 
movie file, overwriting its existing data. 

myCount ™ myRefAtomSize i tnyAtoml O] : 

SetFPos(inyRefNum, fsFroraStart^ 0); 

myErr “ FSWrite (myKefNijn]. &myCount^ tnyData): 

And we're done! The complete definition of 
MRM_Make Reference Movie is shown in Listing il, 


Listing 11: Adding a contained movie to an alternate 
reference movie 

M UM_MakcRefcf entf Movie 

void MRM_MakeRefe]renceHovle 

(Movie theMovieK Handle theMovieAtom) 

1 

Movie niyMovie “ NULL: 

short lEyRefNum = -1; 

long myAtora[2l: 

Ptr myData = MULL: 

long myCoant: //1he numher of bytes to read or write 

long myHovAtomSize : // of the Liiitire movie atom 

long myRaf Atom^ize; // size of the rdcrcncc movie atom 

unsigned longmyAtomHeaderSize ^ 2 * sizeof(long): 

OSErr myErr = noErr; 


// orcate and opon the ouipui file 

myErr = FSpCreate [&gRaf'MovieSpec . F0UR„CHAR„C0DE ('TVOD ’) » 
MovieFileTypet 0): 
if (myErr 1= noErr) I 

// if the file already exists^ we want to delete it anti reereaic it 
if (myErr = dopFNErr) ( 

myErr - FSpDelete(^gRefMovieSpec): 
if (myErr == noErr) 

myErr = FSpCreate(&gRefMovieSpec, 

F0UR_CHAK_C0BE(‘TVOD'). MovieFlleType. 0); 

I 

if (myErr != ncErr) 
goto bail: 


// if there i$ nu contained movie to llatten into the output file, 

// we can skip most of this code and just go ahead and write the data 
if (theMovle = NULL) i 
myData = ‘theMovieAtoni: 
myCount = myMovAtomSize: 
goto writeData; 

) 

// write a free atom at die start of the hie so that HattenMovieData adds the new 
// movie resotirce and media data far enough into the file to allow room for the 
// reference movie atom 
cnyCoLint = aiyRefAtomSiza: 
tnyData = NewPtrClaar (myRefAtoroSize): 
if (myData -- NULL) I 
myErr “ MemErrorO: 
goto bail: 


*(iong OtflyData ^ EndiatiU3 2..NtoB(myRefAtomSize): 

’(long *)(myDaia sizaof (long)) “ 
EndiariLf32_NtpB(FreeAtoTiiTypE) : 

SEtFPos(myRefNumH fsFromStart» 0): 

FSWritE{tnyRefNum, SiinyCount. myData): 

DisposePtr(myData): 

// close the nie, so that llatieiiMovieData can open it 
FSClose(myRefNam): 

// fliitten the contained movie into the out put file; 

// hccaiLse die t>ui|>ut file already exists and lu'causc we‘re not deleting it, 

// the flattened movie d:ita is ^appended* Iti the existing tbia 
myMovie = FlattenMovieData(theMovla. 

flattenAddMovieToDataFotk | 

f lattetiForcEMovlgResourceBeforeHovieData» 
SigRafMovieSp^c, 

F0UR_CHAR_C0DE(' TVOD’). 
amSyEteinScrlpt. 

OL) : 

myErr - GetHovieaError () : 
if (myErr !“ noErr) 
goto bail; 

// open die output file again and reatl the movie atom 

myErr = FSpOpenDF(ligRefMovieSpec, faRdWrPerm, SiinyRefNum): 
if (myErr 1= noErr) 
goto hail: 

SetFPos[myRefNum. fsFromStart, myRefAtomSize); 
it should put us at the 'moov' atom 
myCount = 8: 

myErr = FSRoad[myRefNum. ^myCount. &(myAtom[0]]): 
if (myErr !> noErr] 
goto hail: 

// swap the size and type data s(> that we c:m use it ht're 
rayAtomiO] - EndianU32_BtoN(myAtom{0]): 
myAtoinill = EndianU3.2_BtoN{myAtoraj 1]) : 

if (myAtom[l] i= MovleAID) I //this should never tt£q}peii 

myErr = paramErr: 
goto bail: 

I 

myData = NewPtrClear [TnyRefAtomSiza + myAtom[0]) : 
if (myData — NULL) I 
myErr MemErrorO; 
goto bail: 


92 


QiuckTime Toolkit 


MacTecii • July 2002 
















All the poorer io mstafl and conffgore 
Mac OS X SGfbrme perfectly, Ome, 


Tte Indii^al Strength Installer From 


New OS. New Software. New Installer. 


Introducing IrstallAnywhere - Mac OS X Edition, the new power tool for your Mac OS X software 
installation. Stop using yesterday's tired old installer tools. Now, you can create industrial strength 
installers that are flexible, intuitive, and royalty-free. Your software will look better than ever and 
install perfectly, every time. 

In stall Anywhere supports all Mac OS X features, like user authentication, file permissions, installing 
icons into the Dock, and offers a fully customizable Aqua look and feel. 

Software innovators (ike Adobe, Apple, Borland, Gracion, UmeWire, and Sun already depend on Zero G 
for their software installation needs. See for yourself why In stall Anywhere - Mac OS X Edition is the new 
power tool for your software. 


InstallAnywhere - The Industrial Strength Installer From Zero G. 

Download a free trial version from http://www.ZeraG.com/gato/mac 



ZERO Q 



OZOD? G Software, tnc. InstallAnywhere and Zero C are trademarks at registered tredemarlt^ of Ztrvt G Software, Inc. Mac Is a trademoTk of Apple Computer, Inc., registered in the U.S. 
and other countries.. Ttre "Built for Mac OS X" graptilc is a Irademark ul Apple Gem pc ter Inc., Used under Iken^. All other trademarks are property of their respective owners. 









// merge the movie ytom that FlattenMo\ieData created with the reference movie atom 
*(long *)rnyData = EndianU32_NtoB(niyRefAtoinSiKe + 
iuyAtam[0]); 

'(long *J CstyData + slzeof (long)) = 

EndianU32_NtoB(MovieAlD) r 

// insert the reference movie atom 

BlockMoveOata('theMovieAtom + myATomHeaderSize, myData + 
myAtomHeaderSlze^ niyRefAtoiaSize): 

// read originaJ movie atom 

myCount “ niyAtoiii[0] - rayAtomlleaderSize: 
myErr = FSRead (myRefNmn^ MyConnt. myData + 
myAtoaiHaaderSlze + myRefAtomSize): 
if (myErr 1= noErr) 
goto bail; 

rayCoont = rayRefAtomSize + myAtom[0]: 
vriteData: 

// write the final movie to disk 

SetFPoaCmyRefNuni, fsFroinStart, 0); 

tnyErr = FSWrlte (mylefNuin. ^myCount, myData) ; 

bail: 

If {myCata != NULL) 

DisposePTr(myData) : 

If [myRefNiim != -1) 

FSClose(iEyRefNim) : 

HUnlock(theKavieAtom); 

) 


Conclusion 

Alternate track groups provide a simple but effective way to 
tailor a QuickTime movie for playback in different languages and 
t)n computers with different sound and video hardware. They do, 
however, have their limitations. For one thing, adding lots of 
alternate tmeks can increase the size of die movie file to the point 
that it’s too bulky for easy weh deployment. More importandy, 
alternate tracks can lie selected based only on the quality or 
language of the tnick. For tliese reasons, it’s generally more useful 
to use alternate reference movies to select one from a set of 
alternate movies. 
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With HvaJ SCM systems, ttie only way to 
quicken the pace is to cut comers - but in the 
long run you pay the price with missed 
deadlines, uncertain contents, buggy releases 
and no way back to previous builds. 

With Perforce, the fast way is always the 
right way Install it fastn learn it fast, execute 
operations fast. With other SCM systems, 
developers face an unpleasant choicer 
do It the right way or do it the fast way. 

Perforce's speed and reliability mean fast is right. 
See how Perforce compares with other 
leading SCM systems at 
http -J/www. perforce.co m/perforce/revi ews. htm I 


Run at fuH speed even with hundreds of users 
and mitlions of fif/es. At the core of Perforce lies 
a relational database with well-keyed tables, 
so simple operations can be accomplished in 
near-zero time. Larger operations {like labeling 
a release and branching) are translated into 
keyed data access, giving Perforce the scalability 
that big projects require. 

Work anywhere. Perforce is efficient over high- 
latency networks such as WANs, the Internet and 
even iow-speed dial-up connections. Requiring 
only TCP/IP, Perforce makes use of a well-tuned 
streaming message protocol for synchronizing 
client workspace with server repository contents. 


Develop and maintain mutdple codeiines. 
Perforce Inter-File Branching'"" lets you merge 
new features and apply fixes between codeiines. 
Smart metadata keeps track of your evolving 
projects even while they develop in parallel. 

Truly cross platform. Perforce runs on more than 
50 operating systems, including Windows and 
nearly every UNIX variation, from Linux and 
Mac OS X to AS4O0 and more. 

Integrate with leading IDEs and defect trackers: 

Visual Studio.NET*, Visual C++*, Visual Basic®, 

JBuilder®, CodeWarrior®, TeamTrack®, Bugzilla '", 
Control Cental^, DevTrack* packages, and more. 


Perforce 

SOFTWARE 

Fast Software Configuration Management www.perforce.com 


Download your free 2-user, non-expiring, full-featured copy now from www.perforce.com 
Free (and friendly) technical support is on hand to answer any and all evaluation questions. 

Ail tradsmarte UEod (lefein are eitharlha tradernaritH oi TEgia»rBd tradafiiEirtB of Unair rBspectivB owners. 
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We're Easier. 


Create anything from prototypes to full professional applications. Just drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your stuff great — 
your ideas! REALbasic creates native compiled applications for Macintosh, Mac OS X and Windows 
without platform-specific adjustments. It's the powerful, easy-to-use tool for creating your own 

software. Each version of your software looks and works just as it should in each environment. 

1- . • • * 

Complex problems shouldn't require complex solutions. The answer is REALbasic. 



REALbasic4.5 


NEW VERSION 


Come see us at Macworld in MacTech Central! Download a free demo, www.realbasic.com 












